Spring Boot Course · Lesson 8

Pagination & Sorting

GET /api/books returns every book in one response. With a dozen seeded rows that's fine; with fifty thousand it's a slow query, a huge JSON payload, and a server straining to hold it all in memory at once. In this lesson you'll hand the client a steering wheel — ask for one page at a time, in the order you want — by changing almost nothing in your code.

The win

Add a single Pageable parameter and your list endpoints accept ?page=&size=&sort= for free — Spring Data does the LIMIT/OFFSET/ORDER BY for you. Responses come back as a clean Page: the slice of rows plus the metadata a UI needs (totalElements, totalPages, current page). You'll also fix a subtle trap — the default page JSON is officially unstable — with one property, and cap the page size so a client can't ask for a million rows.

Why an unbounded list is a bug waiting to happen

A collection endpoint that always returns the whole table has three problems that all grow with your data:

The database reads and ships every matching row.
Your server materializes all of them into objects and JSON in memory at once.
The client downloads and parses a payload it mostly won't show.

Pagination fixes all three by pushing a LIMIT and OFFSET down to the database: fetch page 0, 20 rows, then page 1, and so on. Spring Data has this built into every repository — you mostly just have to ask for it.

Step 1 — Add a book that ties on `year`

The database you bring from Lesson 7 holds five books and five authors, and every book has a different year. That matters here: the first request in this lesson sorts by year, and a sort key that two rows share is exactly what makes pages overlap — the trap Step 6 closes. So add a second book from 2018 to create that tie, through the API you already have. Start the app as it stands at the end of Lesson 7, then create the author first, because the service refuses a book whose authorIds it can't resolve:

curl -i -X POST http://localhost:8080/api/authors \
  -H "Content-Type: application/json" -d '{"name":"Martin Fowler"}'

HTTP/1.1 201
Location: /api/authors/01a0d707-3243-7631-b7fb-3925fbf169a6
Content-Type: application/json

{"id":"01a0d707-3243-7631-b7fb-3925fbf169a6","name":"Martin Fowler"}

Now his book, with the id just returned — as always, copy it from your response, not from the page:

curl -i -X POST http://localhost:8080/api/books \
  -H "Content-Type: application/json" \
  -d '{"title":"Refactoring","year":2018,"authorIds":["01a0d707-3243-7631-b7fb-3925fbf169a6"]}'

HTTP/1.1 201
Location: /api/books/01a0d707-32de-7f35-a606-62b04f032ecd
Content-Type: application/json

{"id":"01a0d707-32de-7f35-a606-62b04f032ecd","title":"Refactoring","year":2018,
 "authors":[{"id":"01a0d707-3243-7631-b7fb-3925fbf169a6","name":"Martin Fowler"}]}

Six books, two of them from 2018. Stop the app — the next steps change code, and Step 4 starts it again.

Step 2 — Accept a `Pageable`

Pageable is Spring Data's bundle of "which page, how big, sorted how." Add it as a controller parameter and Spring builds it automatically from the page, size, and sort query parameters — no @RequestParam wiring needed. The repository's inherited findAll(Pageable) then returns a Page instead of a List:


5 collapsed lines
1
package com.example.library.book;
2

3
import java.net.URI;
4
import java.util.UUID;
5
import jakarta.validation.Valid;
6
import org.springframework.data.domain.Page;
7
import org.springframework.data.domain.Pageable;
8
import org.springframework.data.web.PageableDefault;
23 collapsed lines
9
import org.springframework.http.HttpStatus;
10
import org.springframework.http.ResponseEntity;
11
import org.springframework.web.bind.annotation.DeleteMapping;
12
import org.springframework.web.bind.annotation.GetMapping;
13
import org.springframework.web.bind.annotation.PathVariable;
14
import org.springframework.web.bind.annotation.PostMapping;
15
import org.springframework.web.bind.annotation.PutMapping;
16
import org.springframework.web.bind.annotation.RequestBody;
17
import org.springframework.web.bind.annotation.RequestMapping;
18
import org.springframework.web.bind.annotation.RequestParam;
19
import org.springframework.web.bind.annotation.ResponseStatus;
20
import org.springframework.web.bind.annotation.RestController;
21

22
@RestController
23
@RequestMapping("/api/books")
24
public class BookController {
25

26
    private final BookService books;
27

28
    public BookController(BookService books) {
29
        this.books = books;
30
    }
31

32
    @GetMapping                                          // GET /api/books?authorId=...&page=0&size=20&sort=title
33
    public Page<BookResponse> all(
34
            @RequestParam(required = false) UUID authorId,
35
            @PageableDefault(size = 20, sort = "title") Pageable pageable) {
36
        return books.findAll(authorId, pageable).map(BookResponse::from);
37
    }
23 collapsed lines
38

39
    @GetMapping("/{id}")
40
    public BookResponse byId(@PathVariable UUID id) {
41
        return BookResponse.from(books.getById(id));
42
    }
43

44
    @PostMapping                                         // POST /api/books
45
    public ResponseEntity<BookResponse> create(@Valid @RequestBody CreateBookRequest req) {
46
        Book saved = books.create(req.title(), req.year(), req.authorIds());
47
        URI location = URI.create("/api/books/" + saved.getId());
48
        return ResponseEntity.created(location).body(BookResponse.from(saved));
49
    }
50

51
    @PutMapping("/{id}")
52
    public BookResponse replace(@PathVariable UUID id, @Valid @RequestBody CreateBookRequest req) {
53
        return BookResponse.from(books.replace(id, req.title(), req.year(), req.authorIds()));
54
    }
55

56
    @DeleteMapping("/{id}")
57
    @ResponseStatus(HttpStatus.NO_CONTENT)     // 204 on success
58
    public void delete(@PathVariable UUID id) {
59
        books.delete(id);                      // throws NotFoundException -> 404
60
    }
61
}

The filter from Lesson 6 (?authorId=) is still here — paging and filtering compose. The new imports are org.springframework.data.domain.Page, org.springframework.data.domain.Pageable, and org.springframework.data.web.PageableDefault; java.util.List can go, because nothing in the controller returns one any more (more on @PageableDefault in Step 6).

Push the Pageable down through the layers. The service keeps deciding which query to run (the Lesson 3 rule — the service decides, the controller translates), now handing the page request to whichever repository method it picks:


9 collapsed lines
1
package com.example.library.book;
2

3
import java.util.HashSet;
4
import java.util.List;
5
import java.util.Set;
6
import java.util.UUID;
7
import com.example.library.author.Author;
8
import com.example.library.author.AuthorRepository;
9
import com.example.library.error.NotFoundException;
10
import org.springframework.data.domain.Page;       // new, both of them
11
import org.springframework.data.domain.Pageable;
13 collapsed lines
12
import org.springframework.stereotype.Service;
13

14
@Service
15
public class BookService {
16

17
    private final BookRepository books;
18
    private final AuthorRepository authors;            // new: to resolve author ids
19

20
    public BookService(BookRepository books, AuthorRepository authors) {
21
        this.books = books;
22
        this.authors = authors;
23
    }
24

25
    public Page<Book> findAll(UUID authorId, Pageable pageable) {
26
        return (authorId == null)
27
            ? books.findAll(pageable)                         // inherited from JpaRepository
28
            : books.findByAuthorsId(authorId, pageable);      // our derived query, now paged
29
    }
30

37 collapsed lines
31
    // Replaces findById: the service now decides "not found" and throws instead of returning an Optional.
32
    public Book getById(UUID id) {
33
        return books.findById(id)
34
            .orElseThrow(() -> new NotFoundException("No book with id " + id));
35
    }
36

37
    public Book create(String title, int year, Set<UUID> authorIds) {
38
        Book book = new Book(title, year, requireAuthors(authorIds));
39
        return books.save(book);
40
    }
41

42
    public Book replace(UUID id, String title, int year, Set<UUID> authorIds) {
43
        if (!books.existsById(id)) {
44
            throw new NotFoundException("No book with id " + id);
45
        }
46
        Book book = new Book(title, year, requireAuthors(authorIds));
47
        book.setId(id);
48
        return books.save(book);
49
    }
50

51
    public void delete(UUID id) {
52
        if (!books.existsById(id)) {
53
            throw new NotFoundException("No book with id " + id);
54
        }
55
        books.deleteById(id);
56
    }
57

58
    // Every id must resolve to a real author, or the book isn't created at all.
59
    private Set<Author> requireAuthors(Set<UUID> authorIds) {
60
        List<Author> found = authors.findAllById(authorIds);
61
        if (found.size() != authorIds.size()) {
62
            Set<UUID> missing = new HashSet<>(authorIds);
63
            found.forEach(a -> missing.remove(a.getId()));
64
            throw new NotFoundException("No author with id " + missing);
65
        }
66
        return new HashSet<>(found);
67
    }
68
}

findAll(Pageable) already exists on JpaRepository. For the derived query, just add a Pageable parameter and switch the return type to Page — Spring Data rewrites the rest:

1
package com.example.library.book;
2

3
import java.util.UUID;                                   // List is gone: the derived query returns a Page now
4
import org.springframework.data.domain.Page;
5
import org.springframework.data.domain.Pageable;
6
import org.springframework.data.jpa.repository.JpaRepository;
7

8
public interface BookRepository extends JpaRepository<Book, UUID> {
9

10
    // Traverses the collection: WHERE any of the book's authors has this id, one page at a time
11
    Page<Book> findByAuthorsId(UUID authorId, Pageable pageable);
12

13
    // Is any book still linked to this author? (Spring Data derives an EXISTS query.)
14
    boolean existsByAuthorsId(UUID authorId);
15
}

Page vs. Slice vs. List

A repository paging method can return three shapes. Page<T> is the rich one: the rows plus a second COUNT query so it knows totalElements and totalPages — what you need to render "Page 2 of 9." Slice<T> skips the count (cheaper) and only knows whether a next page exists — good for "Load more" infinite scroll. A plain List<T> honours the paging but drops all metadata. We use Page: with the totals in the response, whoever calls the API can show "Page 2 of 9" or "6 books in total" — a Slice only lets them offer "Load more".

Step 3 — Map the page to DTOs

Notice the controller never builds a Page by hand — it calls .map(BookResponse::from). Page is a functor: map transforms each element while carrying all the metadata across unchanged. So Page<Book> becomes Page<BookResponse> — the same Lesson 6 rule (entities never cross the boundary; map to a DTO at the edge), now one page at a time. The service and repository still speak entities; only the controller maps.

Step 4 — Run it: page and sort from the URL

Restart the app. Three query parameters now steer the endpoint — and you didn't write code for any of them:

page — which page, zero-based (page=0 is the first page).
size — rows per page.
sort — field,direction, e.g. sort=year,desc. Repeat the parameter to sort by several fields.

# Page 0, three per page, newest first
curl -s "http://localhost:8080/api/books?size=3&page=0&sort=year,desc"

The books come back in the right order and the response carries the paging metadata — but look closely at the shape of that metadata:

{
  "content": [
    { "id": "01a0d23d-81cd-…", "title": "Effective Java",     "year": 2018, "authors": [ { "id": "…", "name": "Joshua Bloch" } ] },
    { "id": "01a0d707-32de-…", "title": "Refactoring",        "year": 2018, "authors": [ { "id": "…", "name": "Martin Fowler" } ] },
    { "id": "01a0d23f-3f2d-…", "title": "Clean Architecture", "year": 2017, "authors": [ { "id": "…", "name": "Robert C. Martin" } ] }
  ],
  "empty": false,
  "first": true,
  "last": false,
  "number": 0,
  "numberOfElements": 3,
  "pageable": {
    "offset": 0, "pageNumber": 0, "pageSize": 3, "paged": true,
    "sort": { "empty": false, "sorted": true, "unsorted": false },
    "unpaged": false
  },
  "size": 3,
  "sort": { "empty": false, "sorted": true, "unsorted": false },
  "totalElements": 6,
  "totalPages": 2
}

That's a lot of sprawl — and worse, the server logged a warning the moment it serialized this:

WARN ... PageModule$WarningLoggingModifier :
  Serializing PageImpl instances as-is is not supported, meaning that there is no
  guarantee about the stability of the resulting JSON structure!
  For a stable JSON structure, please use Spring Data's PagedModel …

Why returning a raw Page is a trap

Page's default implementation, PageImpl, is an internal domain type, not a designed API response. Jackson will happily serialize all its fields — but the Spring team makes no promise that this structure stays the same across versions. Build a client against pageable.pageNumber today and a future upgrade could rename or move it. The warning is Spring telling you: pin down a stable contract before you ship.

Step 5 — Stabilize the JSON with one property

The fix is a single property that switches Spring to a small, guaranteed-stable page representation called PagedModel. Your controllers keep returning Page<BookResponse> — Spring renders it in the stable shape automatically:

1
# Hibernate never alters the schema - Liquibase owns it. Just verify entities match the tables.
2
spring.jpa.hibernate.ddl-auto=validate
3

4
# Render Page results in the stable { content, page } shape (PagedModel) instead of raw PageImpl
5
spring.data.web.pageable.serialization-mode=via_dto

Why a property and not the annotation?

The reference docs also show the @EnableSpringDataWebSupport annotation with pageSerializationMode = VIA_DTO. On Spring Boot, that annotation replaces Boot's own Spring Data web auto-configuration — so every spring.data.web.pageable.* property, including the size cap you'll add in Step 6, is silently ignored (verified: ?size=99999 came back as 2000 with the annotation in place, not the lowered cap). The property keeps Boot's auto-configuration in charge, so both the stable shape and the size cap work together.

Restart and re-run the same request. The warning is gone, and the metadata collapses to exactly what a client needs — the rows under content, the paging facts under one tidy page object:

{
  "content": [
    { "id": "01a0d23d-81cd-…", "title": "Effective Java",     "year": 2018, "authors": [ { "id": "…", "name": "Joshua Bloch" } ] },
    { "id": "01a0d707-32de-…", "title": "Refactoring",        "year": 2018, "authors": [ { "id": "…", "name": "Martin Fowler" } ] },
    { "id": "01a0d23f-3f2d-…", "title": "Clean Architecture", "year": 2017, "authors": [ { "id": "…", "name": "Robert C. Martin" } ] }
  ],
  "page": {
    "size": 3,
    "number": 0,
    "totalElements": 6,
    "totalPages": 2
  }
}

This is the contract to build a UI on: content is the current slice, page.totalPages drives the pager, page.number is where you are. Ask for the next page and only number (and the rows) change:

curl -s "http://localhost:8080/api/books?size=3&page=1&sort=year,desc"
# -> content = ["Clean Code", "Domain-Driven Design", "The Pragmatic Programmer"]
#    page    = { "size": 3, "number": 1, "totalElements": 6, "totalPages": 2 }

Step 6 — Sane defaults and a safety cap

Two production touches. First, @PageableDefault (already on the handler in Step 2) decides what an unparameterized request gets. Without it, a bare GET /api/books uses Spring's global default of 20 rows, unsorted; with it you set a sensible page size and a default sort so results never come back in arbitrary order:

1
@PageableDefault(size = 20, sort = "title") Pageable pageable

Second — and this one matters for safety — the page size is capped. Spring caps size at spring.data.web.pageable.max-page-size (default 2000). Lower it to something realistic for your API — a request for a million rows quietly becomes a request for, say, 100. It goes right below the serialization-mode property from Step 5, in the same file — all three paging settings live in one place:

1
# Hibernate never alters the schema - Liquibase owns it. Just verify entities match the tables.
2
spring.jpa.hibernate.ddl-auto=validate
3

4
# Render Page results in the stable { content, page } shape (PagedModel) instead of raw PageImpl
5
spring.data.web.pageable.serialization-mode=via_dto
6

7
# Cap how many rows one page request can pull
8
spring.data.web.pageable.max-page-size=100
9
# (optional) change the default page size for unparameterized requests
10
spring.data.web.pageable.default-page-size=20

Restart, and a client can't escape pagination by asking for everything:

curl -s "http://localhost:8080/api/books?size=99999"
# -> page = { "size": 100, "number": 0, "totalElements": 6, "totalPages": 1 }
#    the requested 99999 was clamped to 100

Sort on something unique, or pages will shuffle — and make it the server's job

Pagination is just LIMIT/OFFSET over an ORDER BY. If the sort key isn't unique — say two books share a year — the database may order the ties differently between queries, so the same row can appear on page 1 and page 2, or vanish entirely. The cure is a tie-breaker on a unique column, giving a total order like ORDER BY year DESC, id ASC. But guaranteeing that order is a correctness invariant of your API — too important to depend on whether each client remembers to append &sort=id. Enforce it in the handler: take whatever sort arrives and append id if it isn't already there.

That guarantee is stateless and identical for every paged endpoint, so define it once as a small helper rather than inlining it in each controller (and copy-pasting it into the next). In package-by-feature, a cross-cutting utility earns its own home:

1
package com.example.library.util;
2

3
import org.springframework.data.domain.PageRequest;
4
import org.springframework.data.domain.Pageable;
5
import org.springframework.data.domain.Sort;
6

7
public final class Pageables {
8

9
    private Pageables() {}   // utility class, never instantiated
10

11
    // Append the unique id as a final sort key (if absent) so paging is deterministic.
12
    public static Pageable withIdTiebreaker(Pageable pageable) {
13
        Sort sort = pageable.getSort();
14
        boolean hasId = sort.stream().anyMatch(o -> o.getProperty().equals("id"));
15
        return hasId ? pageable
16
            : PageRequest.of(pageable.getPageNumber(), pageable.getPageSize(), sort.and(Sort.by("id")));
17
    }
18
}

Now the handler stays a one-liner — it just runs the incoming Pageable through the helper before querying. No new imports in the controller beyond Pageables itself:


5 collapsed lines
1
package com.example.library.book;
2

3
import java.net.URI;
4
import java.util.UUID;
5
import jakarta.validation.Valid;
6
import com.example.library.util.Pageables;
26 collapsed lines
7
import org.springframework.data.domain.Page;
8
import org.springframework.data.domain.Pageable;
9
import org.springframework.data.web.PageableDefault;
10
import org.springframework.http.HttpStatus;
11
import org.springframework.http.ResponseEntity;
12
import org.springframework.web.bind.annotation.DeleteMapping;
13
import org.springframework.web.bind.annotation.GetMapping;
14
import org.springframework.web.bind.annotation.PathVariable;
15
import org.springframework.web.bind.annotation.PostMapping;
16
import org.springframework.web.bind.annotation.PutMapping;
17
import org.springframework.web.bind.annotation.RequestBody;
18
import org.springframework.web.bind.annotation.RequestMapping;
19
import org.springframework.web.bind.annotation.RequestParam;
20
import org.springframework.web.bind.annotation.ResponseStatus;
21
import org.springframework.web.bind.annotation.RestController;
22

23
@RestController
24
@RequestMapping("/api/books")
25
public class BookController {
26

27
    private final BookService books;
28

29
    public BookController(BookService books) {
30
        this.books = books;
31
    }
32

33
    @GetMapping                                          // GET /api/books?authorId=...&page=0&size=20&sort=title
34
    public Page<BookResponse> all(
35
            @RequestParam(required = false) UUID authorId,
36
            @PageableDefault(size = 20, sort = "title") Pageable pageable) {
37
        return books.findAll(authorId, Pageables.withIdTiebreaker(pageable)).map(BookResponse::from);
38
    }
23 collapsed lines
39

40
    @GetMapping("/{id}")
41
    public BookResponse byId(@PathVariable UUID id) {
42
        return BookResponse.from(books.getById(id));
43
    }
44

45
    @PostMapping                                         // POST /api/books
46
    public ResponseEntity<BookResponse> create(@Valid @RequestBody CreateBookRequest req) {
47
        Book saved = books.create(req.title(), req.year(), req.authorIds());
48
        URI location = URI.create("/api/books/" + saved.getId());
49
        return ResponseEntity.created(location).body(BookResponse.from(saved));
50
    }
51

52
    @PutMapping("/{id}")
53
    public BookResponse replace(@PathVariable UUID id, @Valid @RequestBody CreateBookRequest req) {
54
        return BookResponse.from(books.replace(id, req.title(), req.year(), req.authorIds()));
55
    }
56

57
    @DeleteMapping("/{id}")
58
    @ResponseStatus(HttpStatus.NO_CONTENT)     // 204 on success
59
    public void delete(@PathVariable UUID id) {
60
        books.delete(id);                      // throws NotFoundException -> 404
61
    }
62
}

A client's ?sort=year,desc now runs as year DESC, id ASC; a request with no sort becomes title ASC, id ASC; and a client that already sorts by id is left untouched — no duplicate clause, and their chosen direction wins. The server's contract is simply "a unique key is always in the ORDER BY," not "id is forced to the end." And because our id is a time-ordered UUIDv7, that tiebreaker is also meaningful — a stable, insertion-ordered fallback, a quiet payoff of the Lesson 5 id choice.

Where the two responsibilities split

The client owns which field to sort by and which page to fetch — that's its UX. The server owns the guarantee that the resulting order is total and stable so paging stays honest, which is why it lives in your code, not the query string. One shared Pageables.withIdTiebreaker keeps that guarantee in a single place — every endpoint calls the same method. Its one weakness: a brand-new endpoint could forget to call it. When you have enough paged endpoints that this worries you, promote the helper to a custom Pageable argument-resolver — then every Pageable arrives already hardened and the call disappears from the controllers entirely.

Do the same for authors

GET /api/authors has the identical unbounded-list problem. The change is mechanical — mirror all of the above:

AuthorService.findAll takes a Pageable and returns Page<Author> (delegating to the inherited authors.findAll(pageable));
AuthorController.all takes @PageableDefault(size = 20, sort = "name") Pageable and returns authors.findAll(Pageables.withIdTiebreaker(pageable)).map(AuthorResponse::from) — the same helper, so the deterministic-order guarantee is defined once and reused, not copied.

No repository change is needed — findAll(Pageable) is inherited. The serialization-mode property is global, so the authors endpoint gets the stable shape too.

Pagination caps the blast radius — it doesn't fix N+1

Each book in a page still lazily loads its authors set to build the nested author responses — so a page of 20 books fires up to 20 extra queries against the join table (the N+1 problem from Lesson 6, now bounded by page size instead of table size). Paging makes the damage finite, but the right fix — fetching the authors in one query — is the whole subject of the next lesson.

If it doesn't behave

sort=year,desc seems ignored? The sort field must be the entity property name (year, title), not the DB column or the JSON field. A typo'd property is silently dropped, leaving the result unsorted.
Getting the sprawling JSON with a logged warning? The spring.data.web.pageable.serialization-mode=via_dto property is missing from application.properties, or you edited the wrong properties file — it must be on the classpath at startup.
?size=5000 only returns 2000 (or 100) rows? Working as intended — that's the max-page-size cap protecting the server.

Check yourself

Answer from memory before revealing.

You add a Pageable parameter to a controller method. Where do page, size, and sort come from?

Why does Spring warn against returning a raw Page (PageImpl) as JSON?

What does page.map(BookResponse::from) do to the paging metadata?

Two books share the same year and you sort only by year. What can go wrong across pages?

Read this next

Primary source: the Spring Data reference on web support & pagination — the authoritative description of Pageable resolution, the PageImpl serialization problem, and the VIA_DTO / PagedModel fix you used here. For a gentler walkthrough with more examples, Paging with Spring Boot (Reflectoring) is excellent.

Glossary: the terms this lesson introduces are in the Glossary, under Lesson 8 — your quick-reference for every term we use.

Architecture decisions: the 5 choices this lesson makes, each with its reason, are in Architecture Decisions, under Lesson 8.

Code: the project at the end of this lesson · what changed in this lesson, exercises included.

💬 Discuss