Files and multipart

A method with @RequestPart parameters sends a multipart/form-data body, one part per parameter: files, text fields and JSON parts. MultipartFile is the same type controllers receive, so a file a controller received can be passed on as it is.

Why

Uploads (a cover image, a document with its metadata) need a multipart body with boundaries, content types and file names. Written by hand it is fiddly; declared with @RequestPart, the client builds it from the arguments.

Example

@FeignClient('catalog', url: r'${catalog.url}')
abstract interface class CatalogFiles {
  // Uploads a book's cover with its description.
  @PostMapping.of(path: '/books/{isbn}/files', consumes: MediaType.multipartFormData)
  Future<UploadResult> upload(
    @PathVariable() String isbn,
    @RequestPart('file') MultipartFile file,   // a file part
    @RequestPart('meta') FileMeta meta,        // an object: a JSON part
    @RequestPart('note') String? note,         // a text field; left out when null
    @RequestParam('draft') bool draft,         // still a query parameter: ?draft=false
  );
}

await files.upload(
  '978-0',
  InMemoryMultipartFile('file', bytes, originalFilename: 'cover.png'),
  FileMeta(title: 'Cover'),
  'first edition',
  false,
);

Parts

@RequestPart('x') parameter Part
MultipartFile A file. Its file name and content type come from the file (else the type is guessed from the file name, else application/octet-stream). The part is named after the annotation, not after file.name.
List<MultipartFile> One file part per file, all named x.
Uint8List, List<int> A file part without a file name (application/octet-stream).
String, numbers, bool, enums, DateTime (or a List of them) A text field (one per item), written as query parameters are.
an object, a Map, a List of objects A JSON part (application/json), written with the client's ObjectMapper.

How the body is built

The body is built in memory once per call, reading each file once, so retries send the same bytes. There is no streaming upload yet: very large files are held in memory during the call.

In Spring (Java)

@PostMapping(value = "/books/{isbn}/files", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
UploadResult upload(@PathVariable String isbn, @RequestPart("file") MultipartFile file);

The same annotations. A list of plain values in a @RequestPart is sent as one text field per item.

See also