Spring Boot and HAL-JSON: Switch to HAL-JSON as default response format

Short introduction

HAL JSON is now the default media type for hypermedia support in Spring. This means that from Spring HATEOAS 2.x and up, including Spring Boot 3.x, HAL JSON is used by default for APIs. So what does this mean for your applications.

What is hypermedia?

Hypermedia is a concept where resources in a REST API are not just data but also include links to related resources and actions. This means that the API responses contain information about what can be done next, allowing clients to navigate through the API dynamically, just like how you click links on a website to move from page to page.

In practice, hypermedia allows an API to guide clients by embedding links inside the response. These links describe available operations or related resources, so clients don't have to hardcode URLs or guess how to interact with the API.

What is HAL-JSON?

HAL-JSON stands for Hypertext Application Language. It's a simple, lightweight format that helps to structure REST API responses by including both the data and the related links in a consistent way. The main goal of HAL-JSON is to make APIs more discoverable and easier to navigate by embedding hyperlinks directly into the response.

In HAL-JSON, links to related resources are placed under the special _links section, while the actual resource data remains at the root of the JSON object. This allows clients to easily find and follow links without guessing how to interact with the API.

spring-boot-starter-hateoas

spring-boot-starter-hateoas is the Spring Boot starter, that makes it easy to build hypermedia-driven REST APIs using Spring HATEOAS. It provides all the necessary dependencies and auto-configuration to help you create APIs that include hypermedia links, following formats like HAL-JSON.

When you add spring-boot-starter-hateoas to your project, you can easily create resources that contain both data and links using types like EntityModel, CollectionModel, and PagedModel. Spring will automatically render these resources in HAL-JSON format by default (starting with Spring Boot 3.x).

Potential issues when migrating to Spring Boot 3.x

When you migrate your application to Spring Boot 3 or higher, one important change to be aware of is that the links section in your API responses will now appear as _links. This change comes from the use of the HAL-JSON format (application/hal+json), which is now the default media type for hypermedia-driven APIs in Spring Boot 3.x and Spring HATEOAS 2.x and up. HAL-JSON is widely adopted as a standard for hypermedia APIs, making it a good time to migrate your APIs to use this format instead of plain application/json.

A potential issue during migration is that your application may still compile and run without errors, but problems could arise once it's deployed to production. Other applications, services, or websites that consume your API must be able to accept HAL-JSON responses. If they are strictly configured to accept only application/json as the Content-Type, they may reject the response or fail to parse it correctly.

To avoid this, you need to:

1. Make sure your API consumers accept application/hal+json or are configured to accept broader content types like application /* or */*.

2. Communicate the change clearly to any teams or clients consuming your API.

3. Consider offering backwards compatibility by supporting both formats temporarily. For example, in Spring HATEOAS, you can create a custom RepresentationModel that includes both _links (for HAL-JSON clients) and a legacy links field for older clients that expect it. This way, the API response contains both sections, allowing older clients to continue working while newer clients can use the HAL-standard _links.

Failing to handle this could lead to unexpected production issues, especially in systems where clients are not prepared for HAL-JSON responses.