Spring HATEOAS - Quick Reference

Full Reference: See advanced.md for affordances (HAL-FORMS), embedded resources, link relations, media types, and testing patterns.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: spring-hateoas for comprehensive documentation.

Dependencies

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

Core Concepts

Richardson Maturity Model: Level 0: Plain Old XML/JSON (single endpoint) Level 1: Resources (multiple endpoints) Level 2: HTTP Verbs (GET, POST, PUT, DELETE) Level 3: Hypermedia Controls (HATEOAS) ← This!

EntityModel Wrapper

@GetMapping("/users/{id}") public EntityModel<User> getUser(@PathVariable Long id) { User user = userService.findById(id);

return EntityModel.of(user,
    linkTo(methodOn(UserController.class).getUser(id)).withSelfRel(),
    linkTo(methodOn(UserController.class).getAllUsers()).withRel("users"),
    linkTo(methodOn(OrderController.class).getOrdersByUser(id)).withRel("orders")
);

}

Response Format (HAL)

{ "id": 1, "name": "John Doe", "_links": { "self": { "href": "http://localhost:8080/api/users/1" }, "users": { "href": "http://localhost:8080/api/users" }, "orders": { "href": "http://localhost:8080/api/users/1/orders" } } }

CollectionModel

@GetMapping("/users") public CollectionModel<EntityModel<User>> getAllUsers() { List<User> users = userService.findAll();

List<EntityModel<User>> userModels = users.stream()
    .map(user -> EntityModel.of(user,
        linkTo(methodOn(UserController.class).getUser(user.getId())).withSelfRel()
    ))
    .toList();

return CollectionModel.of(userModels,
    linkTo(methodOn(UserController.class).getAllUsers()).withSelfRel()
);

}

RepresentationModelAssembler

@Component public class UserModelAssembler implements RepresentationModelAssembler<User, EntityModel<User>> {

@Override
public EntityModel<User> toModel(User user) {
    return EntityModel.of(user,
        linkTo(methodOn(UserController.class).getUser(user.getId())).withSelfRel(),
        linkTo(methodOn(UserController.class).getAllUsers()).withRel("users")
    );
}

}

// Usage @RestController @RequestMapping("/api/users") @RequiredArgsConstructor public class UserController { private final UserService userService; private final UserModelAssembler assembler;

@GetMapping("/{id}")
public EntityModel<User> getUser(@PathVariable Long id) {
    return assembler.toModel(userService.findById(id));
}

@GetMapping
public CollectionModel<EntityModel<User>> getAllUsers() {
    return assembler.toCollectionModel(userService.findAll());
}

}

Pagination Support

@GetMapping("/users") public PagedModel<EntityModel<User>> getAllUsers( @PageableDefault(size = 20) Pageable pageable, PagedResourcesAssembler<User> pagedAssembler) {

Page<User> users = userService.findAll(pageable);
return pagedAssembler.toModel(users, userModelAssembler);

}

Best Practices

Do Don't

Use ModelAssembler pattern Build links inline everywhere

Include self links always Omit navigation links

Use standard IANA relations Invent new relation names

Add conditional links for actions Show all links regardless of state

When NOT to Use This Skill

• Simple REST APIs - If clients don't need hypermedia navigation

• GraphQL APIs - Use spring-graphql instead

• Internal microservices - Often unnecessary overhead

Anti-Patterns

Anti-Pattern Problem Solution

Building links inline Duplicated code everywhere Use RepresentationModelAssembler

Missing self links Clients can't identify resources Always add withSelfRel()

Hardcoded URLs Breaks on deployment Use linkTo/methodOn builders

Inventing relations Non-standard, hard to understand Use IANA link relations

Quick Troubleshooting

Problem Diagnostic Fix

Links not serialized Check Accept header Ensure HAL media type

NullPointerException in linkTo Check controller method Verify method signature matches

Wrong base URL Check proxy config Configure server.forward-headers-strategy

Pagination links missing Check assembler Use PagedResourcesAssembler

Production Checklist

• ModelAssemblers for all resources

• Self links on every resource

• Collection links from items

• Pagination with navigation links

• Conditional action links

• IANA link relations where possible

Reference Documentation

• Spring HATEOAS Reference