Uploading images and files is one of the most common requirements in modern web applications. Whether you are building a social platform, an e-commerce website, a document management system, or a mobile backend, your application will likely need to receive files from users.
Spring Boot provides built-in support for handling file uploads through multipart requests, making implementation straightforward and efficient.
This guide explains how to:
- Create a Spring Boot endpoint for image uploads
- Receive files using multipart/form-data
- Save uploaded files on the server
- Configure upload limits
- Test file uploads using Postman
Understanding Multipart File Uploads
When uploading files through HTTP, the request is typically sent using the multipart/form-data content type.
Instead of sending JSON data, the request contains multiple parts:
- Form fields
- Images
- Documents
- Other binary content
A typical upload request may look like:
POST /upload
Content-Type: multipart/form-data
The uploaded file is attached as one part of the request.
Creating a Spring Boot Upload Endpoint
Spring Boot provides the MultipartFile interface for receiving uploaded files.
Example Controller
@RestController
@RequestMapping("/api")
public class FileUploadController {
@PostMapping("/upload")
public ResponseEntity<String> uploadFile(
@RequestParam("file") MultipartFile file) {
if (file.isEmpty()) {
return ResponseEntity.badRequest()
.body("No file selected");
}
try {
String uploadDir = "uploads/";
File directory = new File(uploadDir);
if (!directory.exists()) {
directory.mkdirs();
}
String filePath =
uploadDir + file.getOriginalFilename();
file.transferTo(new File(filePath));
return ResponseEntity.ok(
"File uploaded successfully");
} catch (Exception e) {
return ResponseEntity.internalServerError()
.body("Upload failed");
}
}
}
How MultipartFile Works
Spring automatically converts the uploaded file into a MultipartFile object.
Useful methods include:
file.getOriginalFilename();
file.getContentType();
file.getSize();
file.isEmpty();
file.getBytes();
Example:
System.out.println(file.getOriginalFilename());
System.out.println(file.getContentType());
System.out.println(file.getSize());
Output:
image.jpg
image/jpeg
1048576
Configuring Upload Limits
Spring Boot allows file size restrictions through application properties.
application.properties
spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=20MB
application.yml
spring:
servlet:
multipart:
max-file-size: 10MB
max-request-size: 20MB
These settings help protect the application from excessively large uploads.
Testing File Uploads with Postman
Postman is one of the easiest tools for testing multipart file uploads.
Step 1: Create a POST Request
Select:
POST
Enter the endpoint:
http://localhost:8080/api/upload
Step 2: Open the Body Tab
Select:
Body
Choose:
form-data
Step 3: Add a File Parameter
Create a row:
| Key | Type | Value |
|---|---|---|
| file | File | Select Image |
Important:
The key name must match the parameter name used in the controller:
@RequestParam("file")
Step 4: Select the Image
Change the parameter type from:
Text
to:
File
A “Select Files” button will appear.
Choose an image from your computer.
Example:
vacation-photo.jpg
Step 5: Send the Request
Click:
Send
If everything is configured correctly, you should receive:
File uploaded successfully
Common Postman Mistakes
Wrong Parameter Name
Controller:
@RequestParam("file")
Postman:
image
This causes:
Required request part 'file' is not present
Always ensure the names match.
Sending JSON Instead of form-data
Incorrect:
{
"file": "image.jpg"
}
Correct:
Body
-> form-data
-> file
-> File
File Type Left as Text
If Postman parameter type remains:
Text
the filename is sent as text instead of uploading the file.
Change the parameter type to:
File
Supporting Multiple Image Uploads
Spring can accept multiple files at once.
Controller
@PostMapping("/upload")
public ResponseEntity<String> uploadFiles(
@RequestParam("files")
MultipartFile[] files) {
for (MultipartFile file : files) {
System.out.println(
file.getOriginalFilename());
}
return ResponseEntity.ok("Uploaded");
}
Postman
Add multiple rows using:
files
or select multiple files in one field depending on your Postman version.
Validating Image Types
For security reasons, it is recommended to validate uploaded content.
Example:
String contentType = file.getContentType();
if (!contentType.startsWith("image/")) {
return ResponseEntity.badRequest()
.body("Only images allowed");
}
Accepted examples:
image/jpeg
image/png
image/gif
image/webp
Storing Images in Cloud Storage
In production systems, images are usually not stored directly on the application server.
Common alternatives include:
- Amazon S3
- Google Cloud Storage
- Microsoft Azure Blob Storage
- Network file systems
- Dedicated media servers
This approach improves scalability and reliability.
Security Considerations
When accepting uploads:
- Validate file type
- Limit file size
- Sanitize filenames
- Scan files for malware when required
- Store files outside the web root when possible
- Generate unique filenames to prevent overwriting
Example:
String filename =
UUID.randomUUID() + ".jpg";
Conclusion
Spring Boot makes image uploads simple through the MultipartFile interface and built-in multipart support. By creating a POST endpoint, configuring upload limits, and testing with Postman using form-data, developers can quickly implement reliable file upload functionality.
For Postman testing, remember the three most important rules:
- Use POST
- Select Body → form-data
- Change the parameter type to File and choose the image from your computer
Following these practices provides a solid foundation for image uploads in both development and production environments.
