
# 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

```dart
@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`. |

- `InMemoryMultipartFile` builds a file from bytes, or from text with `InMemoryMultipartFile.fromString`.
- A nullable parameter leaves its part out for `null`.
- `consumes: MediaType.multipartFormData` is optional; any other `consumes` stops the application at startup.
- `@RequestParam`, `@RequestHeader` and `@PathVariable` work as on any other method; `@RequestParam` stays in the query, as in Spring Cloud OpenFeign.
- The `Content-Type` is `multipart/form-data; boundary=...`.
- A method with both `@RequestPart` and `@RequestBody`, or a parameter with `@RequestPart` and another annotation, stops the application at startup.

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

```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

- [Methods](methods.md)
- [Uploads in the web starter](../spring-boot-starter-web/streaming/uploads.md)
