When building hypermedia-driven REST APIs using Spring HATEOAS, a critical decision is how to model your API responses — especially how to wrap your domain data alongside hypermedia links. Spring HATEOAS provides several wrapper classes, mainly Resource (now deprecated), EntityModel, and RepresentationModel. Understanding these and related types like CollectionModel and PagedModel helps you design clean, maintainable, and self-descriptive APIs.
What Are These Types?
1. Resource (Deprecated)
- What it was: A generic wrapper combining a domain object and hypermedia links.
- Why deprecated: The Spring team replaced it with clearer abstractions for better flexibility and clarity.
- Advice: Avoid using it in new applications.
2. EntityModel<T>
EntityModel<T> wraps a single domain entity and allows attaching hypermedia links.
@Entity
public class Book {
@Id private Long id;
private String title;
// getters and setters
}
Example usage in a controller method:
@GetMapping("/books/{id}")
public EntityModel<Book> getBook(@PathVariable Long id) {
Book book = bookService.findById(id);
return EntityModel.of(book,
linkTo(methodOn(BookController.class).getBook(id)).withSelfRel(),
linkTo(methodOn(BookController.class).getAllBooks()).withRel("books"));
}
Here, the Book entity is wrapped inside EntityModel, and two links are added — one self link, and one to the list of all books.
3. RepresentationModel
RepresentationModel is a base class for hypermedia-driven representations that do not contain a domain entity.
Example:
@GetMapping("/api")
public RepresentationModel<?> root() {
RepresentationModel<?> model = new RepresentationModel<>();
model.add(linkTo(methodOn(BookController.class).getAllBooks()).withRel("books"));
model.add(linkTo(methodOn(AuthorController.class).getAllAuthors()).withRel("authors"));
return model;
}
Use RepresentationModel for root endpoints, status resources, or any resource where you want to return only links or metadata without embedding an entity.
Handling Collections of Resources
For collections of resources, Spring HATEOAS provides:
CollectionModel<T>
Wraps a collection of items, typically a collection of EntityModel<T>.
Example:
@GetMapping("/books")
public CollectionModel<EntityModel<Book>> getAllBooks() {
List<EntityModel<Book>> books = bookService.findAll().stream()
.map(book -> EntityModel.of(book,
linkTo(methodOn(BookController.class).getBook(book.getId())).withSelfRel()))
.collect(Collectors.toList());
return CollectionModel.of(books,
linkTo(methodOn(BookController.class).getAllBooks()).withSelfRel());
}
This wraps each Book in an EntityModel, and the whole list is wrapped in a CollectionModel with a self link.
PagedModel<T>
When you want to support pagination, Spring HATEOAS integrates with Spring Data’s Page<T> type.
Example:
@GetMapping("/books")
public PagedModel<EntityModel<Book>> getBooks(Pageable pageable, PagedResourcesAssembler<Book> assembler) {
Page<Book> page = bookService.findAll(pageable);
return assembler.toModel(page, book -> EntityModel.of(book,
linkTo(methodOn(BookController.class).getBook(book.getId())).withSelfRel()));
}
Here:
PagedResourcesAssemblerautomatically builds pagination links (next,prev,first,last).- Each item is wrapped in an
EntityModel.
Summary Table
| Type | Description | Use Case |
|---|---|---|
Resource<T> | Deprecated wrapper for entity + links | Avoid in new code |
EntityModel<T> | Wraps a single entity + links | Single resource with embedded data |
RepresentationModel | Base class for links-only or metadata responses | Root API, status, or pure links |
CollectionModel<T> | Collection of EntityModel or RepresentationModel | Lists of resources |
PagedModel<T> | CollectionModel + pagination metadata and links | Paginated REST collections |
Useful Resources
- Official Spring HATEOAS Reference
- Baeldung Spring HATEOAS Tutorial
- Spring Guides: Building Hypermedia REST APIs
- Spring HATEOAS GitHub Samples
Final Thoughts
Choosing the right model helps keep your API consistent and intuitive:
- Use
EntityModelfor domain objects with links. - Use
RepresentationModelwhen only links or metadata are needed. - Use
CollectionModelandPagedModelfor lists and paginated data.
Mastering these types makes your REST APIs truly RESTful — discoverable, navigable, and self-descriptive.
