
# Mapping annotations

These annotations say which HTTP call a method stands for: the HTTP method, the path, and where each parameter goes (path, query string, header, cookie or body). A server uses them to route a request to the method; a client uses them to build the request.

## Why

One vocabulary for both sides means a client interface can mirror a controller line for line, and a developer who knows one knows the other. The annotations are Spring's, adapted to Dart.

## Example

```dart
// A client for a book catalog (`@FeignClient` comes from spring_boot_starter_feign).
// A @RestController uses the same annotations.
@FeignClient('catalog', url: r'${catalog.url}')
abstract interface class CatalogClient {
  // GET /books/978-0
  @GetMapping('/books/{isbn}')
  Future<Book> find(@PathVariable('isbn') String isbn);

  // GET /books?q=dune&page=0: `page` is optional thanks to its default.
  @GetMapping('/books')
  Future<List<Book>> search(@RequestParam('q') String query, {@RequestParam() int page = 0});

  // GET /books?author=...&year=...: one query parameter per map entry; a header with every call.
  @GetMapping.of(path: '/books', headers: ['X-Api-Version=2'])
  Future<List<Book>> filter(@RequestParam() Map<String, Object?> filters);

  // POST /books with the book as JSON, plus a request id for the logs.
  @PostMapping.of(path: '/books', consumes: MediaType.applicationJson)
  Future<ResponseEntity<Book>> create(
    @RequestBody() Book book,
    @RequestHeader('X-Request-Id') String requestId,
  );

  // No path: the client's base path itself.
  @GetMapping()
  Future<List<Book>> all({@RequestParam('sort') String sort = 'title'});

  // Without a name, {isbn} is bound to the parameter called isbn.
  @DeleteMapping('/books/{isbn}')
  Future<void> delete(@PathVariable() String isbn);
}
```

## The annotations

| Annotation | On | Meaning |
|---|---|---|
| `@GetMapping([path])`, `@PostMapping`, `@PutMapping`, `@PatchMapping`, `@DeleteMapping` | method | The HTTP method and the path (`/books/{isbn}`). Without a path, the base path: the client's, or the controller class's. |
| `@GetMapping.of({path, headers, produces, consumes})`, and the same for the others | method | Every attribute by name. `headers` are `'Name=value'` entries, `produces` the media type of the answer (`Accept`), `consumes` the media type of the body (`Content-Type`). |
| `@RequestMapping([path])`, `@RequestMapping.of({path, method, headers, produces, consumes})` | method, class | Any HTTP method (`method: HttpMethod.head`; `GET` by default). On a controller class: the path prefix of every method. |
| `@PathVariable([name])` | parameter | Fills `{name}` in the path. A client percent-encodes the value. |
| `@RequestParam([name])` | parameter | A query parameter. A `List` repeats it; a `Map` stands for all query parameters. |
| `@RequestHeader([name])` | parameter | A header. A `List` gives several values; a `Map` stands for all headers. |
| `@CookieValue([name])` | parameter | A cookie, in the `Cookie` header. |
| `@RequestBody()` | parameter | The body, as JSON for an object. |
| `@RequestPart([name])` | parameter | One part of a `multipart/form-data` body: a file (`MultipartFile`, `List<MultipartFile>`), a text field, or an object sent as a JSON part. |

Without a name, `@PathVariable()`, `@RequestParam()`, `@RequestHeader()`, `@CookieValue()` and `@RequestPart()` use the parameter's own name (the generator keeps parameter names).

## Required or optional

There is no `required` or `defaultValue` attribute: the Dart parameter says it.

| Parameter | Client | Server |
|---|---|---|
| nullable (`String? q`) | leaves a `null` argument out; a path variable becomes an empty string | passes `null` when the request has no value |
| with a default (`{int page = 0}`) | sends the default when there is no argument | uses the default when there is no value |
| any other | required | answers 400 when the value is missing |

So `@RequestParam(name = "page", defaultValue = "0") int page` is `@RequestParam('page') int page = 0`.

## Headers, produces and consumes

- **On a client**, the mapping's `headers` are sent. The entries that are only conditions for a server (`'Name'`, `'!Name'`, `'Name!=value'`) are ignored, as Spring Cloud OpenFeign does. Feign's own `'Name: value'` is rejected at startup.
- **On a server**, they are conditions the request must meet: `'Name'` (present), `'!Name'` (absent), `'Name=value'` and `'Name!=value'`.
- `produces` and `consumes` take one media type or a comma-separated list, as one `String`.

## For code that reads the annotations

All mapping annotations implement `Mapping` (`method`, `path`, `headers`, `produces`, `consumes`; `path` is `''` when there is none), so a library finds any of them with `annotations.whereType<Mapping>()`. They and `@ExceptionHandler` carry `@BeanMethodAnnotation()`: the generator then records the annotated methods (parameters, their annotations, the result type) in the bean definition, which is where the web server finds them.

## In Spring (Java)

```java
@GetMapping(value = "/books", produces = "application/json")
List<Book> search(@RequestParam("q") String query, @RequestParam(defaultValue = "0") int page);
```

Attributes next to a positional path are written with the `.of` constructor, since Dart cannot combine an optional positional parameter with named ones: `@GetMapping('/books', produces: ...)` is `@GetMapping.of(path: '/books', produces: ...)`. `produces` and `consumes` are a `String`, not an array.

## See also

- [Controller annotations](controller-annotations.md)
- [@RequestMapping in the web starter](../spring-boot-starter-web/controllers/request-mapping.md)
- [Methods of a Feign client](../spring-boot-starter-feign/methods.md)
