
# @RequestParam

`@RequestParam()` binds a controller parameter to a query parameter (`?q=dune`), or else to a field of a form or multipart body.

## Why

Search terms, filters, page numbers and sort orders are inputs of a call that are not part of the resource's address. They travel in the query string. The annotation reads the value, converts it to the parameter's type, and answers a 400 when a required one is missing or does not convert.

Whether a value is required comes from the Dart parameter itself: nullable or with a default is optional, anything else is required. There are no `required` or `defaultValue` attributes.

## Example

```dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

enum Genre { fiction, science, poetry }

@RestController()
@RequestMapping('/api/books')
class BookSearchController {
  // GET /api/books?q=dune&page=2&genre=science
  @GetMapping()
  String search(
    @RequestParam('q') String query, { // required: no q is a 400
    @RequestParam() int page = 0,      // optional: the Dart default
    @RequestParam() Genre? genre,      // optional: null
  }) => '$query, page $page, ${genre?.name ?? 'any genre'}';

  // GET /api/books/by-ids?id=1&id=2, or ?id=1,2: ids is [1, 2].
  @GetMapping('/by-ids')
  List<int> byIds(@RequestParam('id') List<int> ids) => ids;

  // No annotation: a simple type is a query parameter of the same name.
  // GET /api/books/count?max=10
  @GetMapping('/count')
  int count(int max) => max;

  // Every query parameter: GET /api/books/filter?author=herbert&year=1965
  @GetMapping('/filter')
  Map<String, String> filter(@RequestParam() Map<String, String> filters) =>
      filters;

  // Repeated parameters kept: ?tag=a&tag=b gives {'tag': ['a', 'b']}.
  @GetMapping('/tags')
  Map<String, List<String>> tags(
    @RequestParam() Map<String, List<String>> parameters,
  ) => parameters;

  // A form: POST with Content-Type application/x-www-form-urlencoded
  // and the body title=Dune&count=2.
  @PostMapping('/form')
  String form(
    @RequestParam('title') String title,
    @RequestParam('count') int count,
  ) => '$title x$count';
}
```

## Parameters

| Name | Type | Default | Meaning |
|---|---|---|---|
| `name` (positional) | `String?` | `null` | The name of the query parameter or form field. `null`: the name of the Dart parameter. Not used for a `Map` parameter. |

## Where the value comes from

For a parameter named `q`, in this order:

1. the query string (`?q=...`);
2. when the request is a form (`Content-Type: application/x-www-form-urlencoded`), the field `q` of the body;
3. when the request is `multipart/form-data`, the text field `q` of the upload.

A `MultipartFile` or `List<MultipartFile>` parameter takes the uploaded file of that name instead, exactly as `@RequestPart` does (see [Uploads](../streaming/uploads.md)).

## Required, optional, default

| The request has no `q`, and the parameter is | Result |
|---|---|
| nullable: `@RequestParam() String? q` | `null` |
| named with a default: `{@RequestParam() int page = 0}` | left out of the call: `0` |
| optional positional with a default: `[@RequestParam() int page = 0]` | left out of the call: `0` |
| a non-nullable `List<MultipartFile>` that is optional | an empty list |
| anything else | 400 `Required parameter 'q' is not present.` |

An empty value is a value: `?q=` gives `''` to a `String`, and is a 400 for an `int`.

## Types

- **Simple values:** `String`, `int`, `double`, `num`, `bool` (`true`, `on`, `yes`, `1`, `false`, `off`, `no`, `0`), `BigInt`, `DateTime` (ISO 8601), `Duration` (`10s`), `Uri`, enums (by `@JsonValue` or by name in any case), `Object` and `dynamic` (the text).
- **Lists and sets** of simple values take every value of a repeated parameter (`?id=1&id=2`). A single value with commas is split (`?id=1,2`), and spaces around items are trimmed.
- **`Map<String, V>`** takes every parameter: the multipart text fields, the form fields and the query parameters, the query winning on the same name. `V` is a simple type (the first value of each name, converted) or a list of one (every value). The keys keep the names as sent.
- **`MultipartFile`, `List<MultipartFile>`:** uploaded files (see [Uploads](../streaming/uploads.md)).
- **Anything else** stops the start: `the @RequestParam parameter ... is not a simple value`.

A value that does not convert is a 400 problem that names the parameter: `Failed to convert 'page' with value: 'two'`.

## Without an annotation

A parameter of a simple type (or `MultipartFile`) without any annotation is read as a query parameter of its own name, as if it had `@RequestParam()`, as in Spring. A parameter of another type without annotation stops the start, unless it is one of the types the starter fills itself (`ServerHttpRequest`, `HttpHeaders`, ..., see [Headers, cookies and the request](headers-and-cookies.md)) or a `HandlerMethodArgumentResolver` fills it.

## In Spring (Java)

```java
@GetMapping("/api/books")
List<Book> search(@RequestParam("q") String query,
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(required = false) Genre genre) { ... }

@GetMapping("/api/books/filter")
List<Book> filter(@RequestParam Map<String, String> filters) { ... }
```

Differences that matter:

- `@RequestParam(name = "sort", required = false) String sort` is `@RequestParam('sort') String? sort`.
- `@RequestParam(defaultValue = "0") int page` is `{@RequestParam() int page = 0}`. The default is a Dart value, not a text that is converted.
- `MultiValueMap<String, String>` is `Map<String, List<String>>`.
- There is no `@ModelAttribute`: form fields are not bound to an object. Take them one by one, as a `Map`, or as a `@RequestBody() Map<String, String>` (see [@RequestBody](request-body.md)).

## See also

- [@PathVariable](path-variable.md)
- [@RequestBody](request-body.md)
- [Headers, cookies and the request](headers-and-cookies.md)
- [Uploads](../streaming/uploads.md)
