File handling is where many otherwise well-designed APIs cut corners. The result is integrations that work fine for small files and break under production conditions: uploads timing out on slow connections, downloads failing midway through large transfers, clients with no way to resume an interrupted operation. File upload and download have well-established patterns that handle these conditions correctly. Most of them require explicit design choices rather than the defaults.

Simple Upload: When It Is Sufficient

For files under a few megabytes that users upload infrequently, a direct multipart form upload to your API is the simplest approach. The client sends a multipart/form-data POST request with the file as one part and any metadata as additional parts or as a separate JSON field: