In a web application

When spring_boot_starter_web is also among the application's dependencies, the generator adds glue between the two starters: a Pageable or Sort parameter of a controller method is filled from ?page=&size=&sort=, a returned Page is written as Spring Data's stable JSON, and the common data exceptions are answered with 409, 404 or 400 instead of 500. The starters do not depend on each other; the generator joins them.

Why

A list endpoint reads the page, the size and the order from the query, caps the size, checks the sort property and writes the page with its totals. A conflict on save is a 409, a missing row a 404. This is the same in every API, so it is done once, with Spring Data Web's rules and Spring Boot's property names.

Example

@RestController()
@RequestMapping('/api/books')
class BookController {
  BookController(this.books);

  final BookRepository books;

  // GET /api/books?page=1&size=10&sort=year,desc&sort=title
  @GetMapping()
  Future<Page<Book>> list(@PageableDefault(size: 20, sort: ['title']) Pageable pageable) =>
      books.findAllPaged(pageable);

  // GET /api/books/search?sort=title,asc
  @GetMapping('/search')
  Future<List<Book>> search(@RequestParam() String q, @SortDefault(sort: ['year'], direction: Direction.desc) Sort sort) =>
      books.findByTitleContaining(q, sort);
}
{
  "content": [{"id": 3, "title": "Dune", "year": 1965}],
  "page": {"size": 10, "number": 1, "totalElements": 11, "totalPages": 2}
}

Pageable and Sort parameters

The bean pagingArgumentResolvers (a WebMvcConfigurer) fills them:

Request Means
page=2 The page number, from 0 (from 1 with one-indexed-parameters).
size=50 The page size.
sort=title Ascending by title.
sort=year,desc&sort=title By year descending, then title.
Annotation Attributes
@PageableDefault size (10), page (0), sort ([]), direction (Direction.asc): the defaults when the request has none.
@SortDefault sort ([]), direction (Direction.asc).

Properties

Key Default Meaning
spring.data.web.pageable.default-page-size 20 The page size when the request has no size.
spring.data.web.pageable.max-page-size 2000 The largest page size; a larger size is cut to it.
spring.data.web.pageable.one-indexed-parameters false Whether page starts at 1 instead of 0.
spring.data.web.pageable.page-parameter page The name of the page parameter.
spring.data.web.pageable.size-parameter size The name of the size parameter.
spring.data.web.pageable.prefix '' A prefix before the page and size parameter names.
spring.data.web.pageable.qualifier-delimiter _ Between a @Qualifier and the parameter name (x_page).
spring.data.web.sort.sort-parameter sort The name of the sort parameter.

Lower max-page-size for a public API: a client that sends size=2000 still loads 2000 rows.

The Page JSON

A returned Page<T> is written as Spring Data 3.3's stable JSON: content, and page with size, number, totalElements and totalPages. The JSON does not change when the Page implementation does.

Answers to data exceptions

The bean dataAccessExceptionResolver (a HandlerExceptionResolver) answers with a ProblemDetail whose detail is fixed and never shows the exception's message:

Exception Status Detail
OptimisticLockingFailureException 409 The resource was changed by someone else
DuplicateKeyException 409 The resource already exists
EmptyResultDataAccessException 404 Not found
PermissionDeniedDataAccessException 403 Access denied
PropertyReferenceException 400 Invalid sort property
InvalidPagingRequestException 400 Invalid page or sort request
InvalidDataArgumentException 400 Invalid request value

InvalidDataArgumentException is the caller's value (a text with a NUL character, a list longer than a statement binds, a LIKE pattern the database rejects), not a developer's mistake, so the other InvalidDataAccessApiUsageExceptions stay a 500. The web starter logs these answers at debug.

Rules that stay yours

In Spring (Java)

@GetMapping
Page<Book> list(@PageableDefault(size = 20, sort = "title") Pageable pageable) {
  return books.findAll(pageable);
}

The parameters, annotations and properties are Spring Data Web's and Spring Boot's. Spring has no default mapping of data exceptions to 409 or 404: you write a @ControllerAdvice.

See also