@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:

  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).

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

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:

See also