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

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.

See also