@PathVariable
@PathVariable() binds a controller parameter to a {variable} of the mapping's path, such as isbn in /books/{isbn}.
Why
When the path names the resource (/books/978-0, /authors/42/books), the value belongs in the path rather than in the query. The annotation takes it from the matched path, decodes it and converts it to the parameter's type, so the method receives an int or an enum instead of a text to parse.
Example
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
enum Format { pdf, epub }
@RestController()
class BookController {
// GET /books/978-0: isbn is '978-0'.
@GetMapping('/books/{isbn}')
String find(@PathVariable() String isbn) => 'book $isbn';
// The parameter has another name than the variable, so name it.
// GET /authors/42/books: authorId is 42; /authors/x/books is a 400.
@GetMapping('/authors/{id}/books')
String byAuthor(@PathVariable('id') int authorId) => 'author $authorId';
// A regular expression lets only digits in: /orders/abc is a 404.
@GetMapping(r'/orders/{id:\d+}')
String order(@PathVariable() int id) => 'order $id';
// An enum, by name in any case: /downloads/978-0/EPUB.
@GetMapping('/downloads/{isbn}/{format}')
String download(@PathVariable() String isbn, @PathVariable() Format format) =>
'$isbn as ${format.name}';
// The rest of the path, with its leading slash:
// GET /files/docs/a/b.txt: path is '/docs/a/b.txt'.
@GetMapping('/files/{*path}')
String file(@PathVariable() String path) => path;
// A list from one segment: GET /books/batch/1,2,3: ids is [1, 2, 3].
@GetMapping('/books/batch/{ids}')
List<int> batch(@PathVariable() List<int> ids) => ids;
}
Parameters
| Name | Type | Default | Meaning |
|---|---|---|---|
name (positional) |
String? |
null |
The name of the path variable. null: the variable named like the Dart parameter. |
Rules
-
Every variable needs a parameter, and every parameter a variable. A
{variable}without a@PathVariableparameter, or a@PathVariablewhose name is not in the path, stops the start (see Startup checks). -
The value is always there once the path matched, so the parameter needs no default and need not be nullable.
-
Values are decoded.
/books/a%20bgivesa b. An encoded/,\or NUL (%2F,%5C,%00) in the path is refused with a 400 by the server before any filter, so a variable never holds../. -
Matrix parameters are cut off:
/books/1111;v=1givesisbn1111. -
Conversion. The text is converted to the parameter's type:
Type Accepted text String,Object,dynamicas it is int,double,num,BigInta number (spaces around it are trimmed) booltrue,on,yes,1/false,off,no,0, in any caseDateTimeISO 8601 ( 2026-05-01,2026-05-01T10:00:00Z)Duration10s,500ms,2h(the duration formats of the configuration)Uria URI an enum its @JsonValue, else its name in any caseList<T>,Set<T>a comma-separated list of the above A text that does not convert is a 400 problem:
Failed to convert 'id' with value: 'x'(MethodArgumentTypeMismatchException). -
Only simple values. A
@PathVariableof another type (a class of your own, aMap) stops the start. -
A pattern restricts what reaches the method.
{id:\d+}makes/orders/abca 404 instead of a conversion error. When a variable becomes part of a file name, always restrict it this way or check it (see Downloads). -
{*path}captures the rest of the path, with its leading/; it may only be the last segment. -
One parameter, one role. A parameter cannot carry
@PathVariableand another binding annotation (such as@RequestParam) at once.
In Spring (Java)
@GetMapping("/authors/{id}/books")
List<Book> byAuthor(@PathVariable("id") int authorId) { ... }
Differences that matter:
- There is no
requiredattribute. A variable of the pattern is always present. - A path variable without a parameter, or the other way round, stops the start. Spring fails only the requests.
Map<String, String>parameters with all variables are not supported; the variables are in the request attributeuriTemplateVariablesAttribute(request.attributes[uriTemplateVariablesAttribute]).
See also
- @RequestMapping and @GetMapping: path patterns
- @RequestParam
- Startup checks