So Your App is Uploading Files - Here are Key Considerations

Beginner-friendly exploration that covers basic insights and key considerations while creating a feature for uploading files.

Different Ways to Upload files

• Upload from the Frontend, Then Send the Link to the API ( ⚠️ Use with caution)

• Send File as Base64 in Request Body ( 🛑 Avoid if possible)

• Upload from the Backend, Separate Requests for File and Metadata

• Upload from the Backend, Single Request with List of Files and Metadata ( ✅ Leaning Toward This)

• Upload from the Backend, Single File and Metadata per Request - Iterative Approach

Lets explore the above options -

Upload from the Frontend, Then Send the Link to the API :

This approach has major disadvantage of relying on the security of the client's application. It is difficult for backend to ensure that the link is valid and does not point to malicious content. While it may offer some performance or architectural benefits, the disadvantages outweigh the advantages. Use this method only if you have a strong, well-justified reason.

Services like Firebase Storage or AWS S3 with pre-signed URLs can be used and if configured well, can make this approach better.

Send File as Base64 in Request Body :

Another approach that is discouraged to implement. Reason is simple - it increases the payload size significantly and is inefficient for larger files. Additionally, the encoding and decoding process adds unnecessary overhead on both the frontend and backend.

Base64 is used in emails or inline HTML to embed small files like icons or logos directly in the content, but it's not ideal for uploads.

Upload from the Backend, Separate Requests for File and Metadata :

Backend for Uploads, now we are talking!

Upload from Backend is generally secure approach. However sending separate requests, one for files and another for metadata can create complexity. It does not align with stateless RESTful design because it might force you to maintain the state temporarily. Or you might upload the file first, return a file ID, and then expect client to send PUT request with metadata in a second call that references this ID. But this requires careful coordination.

Upload from the Backend, Single Request with List of Files and Metadata :

In most of the cases, user wants to upload multiple files as a single atomic action,  related or unrelated does not matter. So single request should take care of most of the significant actions. It can introduce some complexity of linking correct metadata with the correct file, but this trade-off is worth for long-term scalability. The biggest advantage with this approach is it removes the overhead of multiple network connections. It might reduce network latency as well, but please note latency depends on multiple factors like file size, server configuration etc.

Backend Upload, Single File and Metadata per Request - Iterative Approach :

In this method, each request sends one file along with its metadata, and the process is repeated for all files. It's a straightforward and clean approach that works well for smaller applications or when you expect low upload volume.

However, this can lead to performance issues when uploading many files. Since each upload is a separate request, it introduces O(n) network operations, which may cause bottlenecks, higher latency, and increased resource usage on both the client and server. Still, the simplicity of this method makes it a reasonable choice for small-scale use cases.

Risks of File Upload to Consider

File upload itself should be considered as a serious security risk, if not properly handled. The risk depends on how the uploaded file is used, stored, and processed. Everything should be validated — including file type, size, and contents. A poorly handled upload can allow an attacker to:

• Upload and run malicious scripts

• Access or manipulate server files and confidential data

• Attack other systems on the network

• Exploit vulnerabilities in the backend

  
  

Common Risks to Be Aware Of :

• Client-side attacks, such as XSS or cross-site content hijacking via uploaded content

• Malicious file types, like:

  • Excel files with harmful formulas or embedded scripts

  • Images like .jpg that contain hidden Flash or executable content

  • Shell scripts or malware disguised with common extensions

• Files with double extensions, e.g., file.txt.php or file.jpg.exe, used to bypass filters

• Tricky URL paths, like file.jpg/index.php, where the file may appear safe but still be processed as executable code

• Null byte injection, using control characters like 0x00 to bypass validation (e.g., file.php%00.jpg)

• NTFS alternate data streams (Windows-specific), e.g., file.asax:.jpg, where hidden data can be stored

• Windows 8.3 short filename tricks, e.g., replacing web.config with web~1.con to bypass name restrictions

How to Reduce Risks by Adding Some Basic Protections

Every development team should define basic upload rules that match their application's needs. These don’t have to be overly complex, but following some uniform practices can go a long way.

Basic Upload Rules :

🔔 Rules	💥 Protection Against Risks
Always rename uploaded files – Generate a new name (e.g., using md5 or sha1 hashes) to prevent attackers from using special filenames.	-Tricky URL paths (file.jpg/index.php, embedded PHP code in .jpg) -Files with null byte injection (file.php%00.jpg) -NTFS alternate data streams (e.g., file.asax:.jpg) -Windows 8.3 shortname trick (web.config replaced by web~1.con)
Strictly validate the file type – Don’t rely on extensions; check MIME type or inspect the actual file signature	-Files with double extensions (file.txt.php, file.jpg.exe) -Tricky URL paths (file.jpg/index.php, embedded PHP code in .jpg) -Client-side attacks like XSS or content hijacking -Uploading .jpg files that contain Flash objects
Limit file size and count – Set clear limits on file size and the number of files per request. Use rate limiting to prevent abuse.
Scan for viruses and malware: - Integrate antivirus tools like ClamAV into your Spring Boot app -Look into Google Cloud Armor for additional protection - Consider Google Cloud’s VirusTotal for cloud-native scanning	-Client-side attacks like XSS or content hijacking -Risks running excel with dangerous formulas, scripts, or shell code -Uploading .jpg files that contain Flash objects
Restrict access and permissions – Use IAM roles to control who can upload or view files in your storage.	-NTFS alternate data streams (e.g., file.asax:.jpg) -Windows 8.3 shortname trick (web.config replaced by web~1.con)
Store uploads in object storage – Prefer managed services like Google Cloud Storage over local disk.	NTFS alternate data streams (e.g., file.asax:.jpg)
Enable encryption at rest – Make sure uploaded files are stored securely.
Keep buckets private – Don’t expose your storage buckets publicly unless absolutely necessary.
Use HTTPS – Always protect your API endpoints with TLS (SSL).
Log all upload activity – Store metadata and logs in your database for traceability and audit.
Use chunked uploads for large files – This can improve reliability and user experience, especially for unstable networks.

Something Nice to Consider

While working with REST APIs, using appropriate response code might feel like a "last but not the least" kind of detail, and it sure is. It keeps clear communication with the client application about how the upload process is carried out. That is why it is important to be consistent with HTTP response codes so that the client application can have a uniform way of handling the situation.

200 Ok

201 Created for a successful upload of a new resource(s). Location header for multiple resource creation should either contain URI for the primary resource (RFC 7231) or collection URI itself, with the response body providing the details and unique IDs of all new resources.

202 Accepted to acknowledge complex upload like asynchronous or offloaded

204 No Content when a resource is deleted

400 Bad Request everything bad formatting, unsupported file types (or 415), a missing parameter

401 Unauthorized

403 Forbidden

404 Not Found when a resource does not exist

409 Conflict when a resource is already uploaded

412 Precondition Failed ( Recommended Header ETag with 201 response makes a request conditional)

413 Payload Too Large code if the file size limit exceeds

415 Unsupported Media Type when a file type is not allowed for upload

422 Unprocessable Entity when metadata is incomplete

429 Too Many Requests useful if you implement rate limiting for uploads (e.g., per user or IP)

502 Bad Gateway to show unforeseen errors with networking or cloud platforms

503 Service Unavailable because of outage or database or endpoint unavailability