By WebNest Studio Engineering Team
Spring Boot Tutorial
Hypermedia APIs with Spring HATEOAS
In most JSON APIs, clients hard-code every URL and every rule about what they are allowed to do next. HATEOAS — Hypermedia As The Engine Of Application State — takes a different approach: each response includes links to related resources and to the actions currently possible. An order that can still be cancelled includes a cancel link; a shipped order does not. Clients follow links instead of constructing URLs.
Spring HATEOAS makes building such responses straightforward. This lesson explains the idea, adds self and relation links with WebMvcLinkBuilder, builds collection responses, uses representation model assemblers to keep controllers clean, shows conditional links for state transitions, and discusses when hypermedia is worth it.
Why Hypermedia
Links make an API more self-describing and let the server evolve URLs without breaking clients that follow links. Conditional links move business rules ("can this order be cancelled?") to the server, so web and mobile clients stay consistent. HATEOAS is the top level of the Richardson Maturity Model (see the best-practices lesson). The trade-off is larger responses and more client logic to interpret links, so many internal APIs skip it while public, long-lived APIs benefit most.
Core Types
Spring HATEOAS provides representation models that carry links:
EntityModel<T>— wraps one object plus links.CollectionModel<T>— wraps a collection plus links.PagedModel<T>— a page of results with first/prev/next/last links (built withPagedResourcesAssembler).LinkandLinkRelation— a URL with a relation name such asself,ordersorcancel.WebMvcLinkBuilder.linkTo(methodOn(Controller.class).method(args))— builds links from controller methods, so URLs are never hard-coded.
HAL: The Default Format
Spring HATEOAS renders responses in HAL (application/hal+json): links appear under _links and embedded collections under _embedded. Other media types such as HAL-FORMS (which also describes the fields of available actions) can be enabled when needed.
Representation Model Assemblers
Building links in every controller method gets repetitive. A RepresentationModelAssembler converts a domain object or DTO into an EntityModel with its links in one place, and is reused by all endpoints that return that type.
Examples
Dependency and a resource with self and related links
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-hateoas</artifactId>
</dependency>
import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.*;
@RestController
@RequestMapping("/api/users")
public class UserController {
private final UserService users;
public UserController(UserService users) {
this.users = users;
}
@GetMapping("/{id}")
public EntityModel<UserDto> get(@PathVariable Long id) {
UserDto user = users.get(id);
return EntityModel.of(user,
linkTo(methodOn(UserController.class).get(id)).withSelfRel(),
linkTo(methodOn(UserController.class).all()).withRel("users"),
linkTo(methodOn(PostController.class).postsOf(id)).withRel("posts"));
}
@GetMapping
public CollectionModel<EntityModel<UserDto>> all() {
List<EntityModel<UserDto>> list = users.all().stream()
.map(u -> EntityModel.of(u, linkTo(methodOn(UserController.class).get(u.id())).withSelfRel()))
.toList();
return CollectionModel.of(list, linkTo(methodOn(UserController.class).all()).withSelfRel());
}
}
GET /api/users/7 Accept: application/hal+json
{
"id": 7,
"name": "Asha Rao",
"_links": {
"self": { "href": "http://localhost:8080/api/users/7" },
"users": { "href": "http://localhost:8080/api/users" },
"posts": { "href": "http://localhost:8080/api/users/7/posts" }
}
}
An assembler with conditional state-transition links
@Component
public class OrderModelAssembler implements RepresentationModelAssembler<OrderDto, EntityModel<OrderDto>> {
@Override
public EntityModel<OrderDto> toModel(OrderDto order) {
EntityModel<OrderDto> model = EntityModel.of(order,
linkTo(methodOn(OrderController.class).get(order.id())).withSelfRel(),
linkTo(methodOn(OrderController.class).all(null)).withRel("orders"));
// Only offer actions that are valid in the current state
if (order.status() == OrderStatus.PLACED) {
model.add(linkTo(methodOn(OrderController.class).cancel(order.id())).withRel("cancel"));
model.add(linkTo(methodOn(OrderController.class).pay(order.id())).withRel("pay"));
}
if (order.status() == OrderStatus.SHIPPED) {
model.add(linkTo(methodOn(OrderController.class).track(order.id())).withRel("track"));
}
return model;
}
}
@GetMapping("/{id}")
public EntityModel<OrderDto> get(@PathVariable Long id) {
return assembler.toModel(orders.get(id));
}
Order 41 (PLACED): "_links": { "self": {...}, "orders": {...}, "cancel": {...}, "pay": {...} }
Order 42 (SHIPPED): "_links": { "self": {...}, "orders": {...}, "track": {...} }
(The client shows a Cancel button only when a "cancel" link is present.)
Paged collections with navigation links
@GetMapping
public PagedModel<EntityModel<OrderDto>> all(Pageable pageable) {
Page<OrderDto> page = orders.page(pageable);
return pagedAssembler.toModel(page, assembler); // PagedResourcesAssembler<OrderDto> injected
}
GET /api/orders?page=1&size=2
{
"_embedded": { "orderDtoList": [ {...}, {...} ] },
"_links": {
"first": { "href": "http://localhost:8080/api/orders?page=0&size=2" },
"prev": { "href": "http://localhost:8080/api/orders?page=0&size=2" },
"self": { "href": "http://localhost:8080/api/orders?page=1&size=2" },
"next": { "href": "http://localhost:8080/api/orders?page=2&size=2" },
"last": { "href": "http://localhost:8080/api/orders?page=9&size=2" }
},
"page": { "size": 2, "totalElements": 20, "totalPages": 10, "number": 1 }
}
Common Mistakes
- Hard-coding URLs in links instead of using linkTo(methodOn(...)), so links break when mappings change.
- Adding every possible action link regardless of state, defeating the purpose of conditional links.
- Forgetting forward-headers support behind a proxy, so links contain internal hostnames or http:// URLs.
- Adopting HATEOAS for a small internal API where clients will never use the links.
- Mixing HAL responses and plain JSON inconsistently across endpoints of the same API.
Exercise
Using the lesson's Dependency and a resource with self and related links example, create a small implementation or design sketch that demonstrates HATEOAS adds links to responses so clients discover related resources and allowed actions.. Add a test case or scenario that would catch Hard-coding URLs in links instead of using linkTo(methodOn(...)), so links break when mappings change., and describe the expected result.
Show hints
- Start with Why Hypermedia and compare your approach with Dependency and a resource with self and related links. Identify the decision or behavior the lesson recommends.
- Walk through your scenario step by step. Confirm that it follows HATEOAS adds links to responses so clients discover related resources and allowed actions. and that it would catch the failure described by Hard-coding URLs in links instead of using linkTo(methodOn(...)), so links break when mappings change..
Quick quiz
1. Which choice is a mistake to avoid in Hypermedia APIs with Spring HATEOAS?
- A. Adding every possible action link regardless of state, defeating the purpose of conditional links.
- B. HATEOAS adds links to responses so clients discover related resources and allowed actions.
- C. Hard-coding URLs in links instead of using linkTo(methodOn(...)), so links break when mappings change.
Show answer
C. Avoid this approach: Hard-coding URLs in links instead of using linkTo(methodOn(...)), so links break when mappings change. The lesson recommends: HATEOAS adds links to responses so clients discover related resources and allowed actions.
Interview questions
A teammate is about to make this mistake: Hard-coding URLs in links instead of using linkTo(methodOn(...)), so links break when mappings change. How would you diagnose and correct it using the lesson's guidance?
Show answer
HATEOAS adds links to responses so clients discover related resources and allowed actions. Apply this in Why Hypermedia; the example Dependency and a resource with self and related links shows one way to do it. Avoid Hard-coding URLs in links instead of using linkTo(methodOn(...)), so links break when mappings change. and explain how your implementation or design prevents that failure.
Key Points to Remember
- HATEOAS adds links to responses so clients discover related resources and allowed actions.
- spring-boot-starter-hateoas provides EntityModel, CollectionModel, PagedModel and WebMvcLinkBuilder.
- Responses use HAL by default: _links and _embedded.
- RepresentationModelAssembler centralises link creation; conditional links express state transitions.
- Use hypermedia for public, evolving APIs where its flexibility pays off.
Practice in the playground
Write and run your own code for this topic, or start from the exercise or an example. Runs plain Java 17. Frameworks such as Spring, and databases, are not available here. Your code for each topic is kept in this browser.
Run the examples
Change an input, predict the result, then compare it with the output. Explain why the result changes.
These examples need a JDK project with their libraries on your computer, so they can be copied but not run here. Codelab runs Python, FastAPI backends with SQLite, plain Java 17 and HTML/CSS/JavaScript.
Written by
WebNest Studio Engineering Team
Practical lessons from developers working with Java, Python, React, databases and production systems.
Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering