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. |
- A size above
max-page-size(2000) is cut to it; a size below one, or missing, is the default (20). - A negative or non-numeric page is 0.
- A sort property the entity does not have is a 400.
@Qualifier('x')on the parameter readsx_page,x_sizeandx_sort, for two pageables in one request.
| 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
- Bind request bodies to DTOs, not entities. An entity binding lets the client choose the id and the version.
- Allow-list sort properties when some must not be sortable: a sort is an
ORDER BYoracle, and a client can learn the order of values it cannot read, such as a password hash. - Validate text that reaches a repository (
@Pattern, no NUL), so a bad value is a 400 from validation rather than from the data layer.
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.