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
// 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
headersare 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'. producesandconsumestake one media type or a comma-separated list, as oneString.
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)
@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.