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

```dart
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 `@PathVariable` parameter, or a `@PathVariable` whose name is not in the path, stops the start (see [Startup checks](startup-checks.md)).
- **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%20b` gives `a 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=1` gives `isbn` `1111`.
- **Conversion.** The text is converted to the parameter's type:

  | Type | Accepted text |
  |---|---|
  | `String`, `Object`, `dynamic` | as it is |
  | `int`, `double`, `num`, `BigInt` | a number (spaces around it are trimmed) |
  | `bool` | `true`, `on`, `yes`, `1` / `false`, `off`, `no`, `0`, in any case |
  | `DateTime` | ISO 8601 (`2026-05-01`, `2026-05-01T10:00:00Z`) |
  | `Duration` | `10s`, `500ms`, `2h` (the [duration formats](../../spring-core-dart/conversion/durations.md) of the configuration) |
  | `Uri` | a URI |
  | an enum | its `@JsonValue`, else its name in any case |
  | `List<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 `@PathVariable` of another type (a class of your own, a `Map`) stops the start.
- **A pattern restricts what reaches the method.** `{id:\d+}` makes `/orders/abc` a 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](../streaming/downloads.md)).
- **`{*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 `@PathVariable` and another binding annotation (such as `@RequestParam`) at once.

## In Spring (Java)

```java
@GetMapping("/authors/{id}/books")
List<Book> byAuthor(@PathVariable("id") int authorId) { ... }
```

Differences that matter:

- There is no `required` attribute. 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 attribute `uriTemplateVariablesAttribute` (`request.attributes[uriTemplateVariablesAttribute]`).

## See also

- [@RequestMapping and @GetMapping](request-mapping.md): path patterns
- [@RequestParam](request-param.md)
- [Startup checks](startup-checks.md)
