Spring Boot File Upload API with MultipartFile
This beginner-to-intermediate guide shows how Spring Boot file upload works in a REST API, from receiving a multipart request with MultipartFile to validating, storing, and returning a useful response without mixing every responsibility into the controller.
Quick Answer
Use MultipartFile to receive the uploaded file, keep request and response handling in the controller, and move validation and storage into services. Generate a safe server-side filename and return a structured success or failure response.
A basic file upload in Spring Boot starts with a multipart/form-data request. The API receives the file, validates its filename, type, and size, stores it outside the web root, and returns an identifier or download reference to the client.
The goal is to keep that flow structured and predictable. A clean Spring Boot file upload API is easier to test, secure, and extend when storage requirements change.
Build a Spring Boot File Upload API
Even a simple endpoint to upload a file in Spring Boot needs clear responsibilities and defensive handling.
- MultipartFile endpoint for multipart request handling
- validation for filename, content type, and file size
- safe local storage with generated names and controlled paths
- useful API responses and consistent upload failure handling
How Multipart File Upload in Spring Boot Works
Understanding the Spring Boot multipart file upload flow keeps the controller thin and makes failures easier to handle.
- Client sends a multipart/form-data request
- Controller receives the file as MultipartFile
- Service validates name, type, size, and empty content
- Storage layer generates a safe name and saves the file
- API returns a file reference or a clear error response
Separate Controller, Service, and Storage Responsibilities
The controller should accept the multipart request, invoke the service, and translate the result into an HTTP response. It should not build file paths, rename files, or write bytes directly.
Keep each responsibility explicit:
- controller handles multipart request and API response
- service validates the file and coordinates the upload
- storage layer saves and retrieves files through controlled paths
Recommended project structure
src/ ├── controller/ ├── service/ ├── storage/ ├── model/ └── config/
Validate and Store Uploaded Files Safely
- trusting the original filename or allowing path traversal
- accepting empty, oversized, or unsupported file types
- hardcoding paths instead of using validated configuration
- returning generic server errors for every upload failure
When to Move from Local Storage to Object Storage
Local storage is practical for learning, prototypes, and a single application instance. Move to object storage when files must survive deployments, multiple instances need shared access, or storage and delivery must scale independently from the API.
When those requirements appear, use the AWS S3 file upload guide to change the storage implementation without turning this basic guide into an S3-specific setup.
- keep the controller and response contract stable
- replace local storage behind a storage abstraction
- add endpoint authentication and authorization separately
Unstructured vs Structured File Upload
Without structure
- file logic inside controllers
- hardcoded paths
- difficult to switch storage
- code duplication
With structure
- clean separation of layers
- easy to extend and maintain
- storage can be swapped
- reusable across projects
Build a Clean File Upload API in Spring Boot
File upload in Spring Boot does not need to be complicated. Receive MultipartFile requests, validate untrusted input, generate safe storage names, separate controller and service responsibilities, and return responses that help clients handle success and failure.
Start with FiloraFS Lite (Spring Boot File Upload Boilerplate)
Start from ready-to-use upload, download, list, and delete APIs with local storage.
View BoilerplateFree and open source
Frequently asked questions
How do I upload files in Spring Boot?
Use MultipartFile in your controller and handle file processing in a separate service layer.
Where should I store uploaded files?
You can start with local storage and later move to cloud storage like S3 without changing your API structure.
Should file upload logic be inside controllers?
No. Keep controllers thin and move file handling to service and storage layers.