
# 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

```dart
@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);
}
```

```json
{
  "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 reads `x_page`, `x_size` and `x_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 `InvalidDataAccessApiUsageException`s 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 BY` oracle, 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)

```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

- [spring_boot_starter_web](../spring-boot-starter-web/index.md)
- [Paging and sorting](paging-and-sorting.md)
- [HandlerExceptionResolver](../spring-boot-starter-web/errors/handler-exception-resolver.md)
