A file upload transfers a file from a consumer to a file-management service or system. Unlike ordinary JSON data, files introduce security, architectural, efficiency, and flow-design concerns that shape the API. section 14.1.1 section 14.3
A banking account application might require a photo proving residence. That upload may be large, rejected by authorization or content rules, processed asynchronously, or delegated to a separate file-management system. Always arrange virus and malware checks with the security team. section 14.1.1 section 14.3 section 14.5
Design upload flows around the consumer’s cost of failure:
- Publish expected document types and size limits so consumers can detect avoidable failures before sending a large file. section 14.4.3
- Use Content-Type, Content-Length, authorization, and path checks to validate a request; reject oversized content with 413 Content Too Large. section 14.4.3
- For large files, support Expect: 100-continue: validate headers first, then accept the body only after 100 Continue. section 14.4.3
- Delegate storage or transfer when security, performance, or architecture makes a dedicated file-management system preferable, while hiding that boundary when possible. section 14.5
Preventing a wasted upload
Before sending a 200 MB proof-of-residence GIF to POST /account-applications/12345/documents, the consumer checks authorization, path access, Content-Type, and Content-Length. With Expect: 100-continue, the server validates these headers first; it returns 100 Continue only when the body may be sent. section 14.4.3
Treat file-upload guidance as an evolving design practice rather than a premature universal recipe. Add detailed rules after the architecture, infrastructure, security, and real use cases are understood. section 16.5.3 section 16.9
