@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
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:
- the query string (
?q=...); - when the request is a form (
Content-Type: application/x-www-form-urlencoded), the fieldqof the body; - when the request is
multipart/form-data, the text fieldqof the upload.
A MultipartFile or List<MultipartFile> parameter takes the uploaded file of that name instead, exactly as @RequestPart does (see Uploads).
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@JsonValueor by name in any case),Objectanddynamic(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.Vis 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).- 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) or a HandlerMethodArgumentResolver fills it.
In Spring (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 sortis@RequestParam('sort') String? sort.@RequestParam(defaultValue = "0") int pageis{@RequestParam() int page = 0}. The default is a Dart value, not a text that is converted.MultiValueMap<String, String>isMap<String, List<String>>.- There is no
@ModelAttribute: form fields are not bound to an object. Take them one by one, as aMap, or as a@RequestBody() Map<String, String>(see @RequestBody).