File Download Feature in Spring Boot

To understand file upload/download in backend development, let’s first get comfortable with what a file really is;

🧱 File Structure: What Makes Up a File?

📌 Types of Files You Might Handle in Web Apps

Now that we understand what a file is and its structure, let’s shift our focus to the backend developer’s perspective — specifically, how to enable file download functionality using Spring Boot.

📄 How to Enable File Download Functionality in Spring Boot (REST API)

When building backend applications, it’s common to allow users to download files they’ve previously uploaded — such as invoices, images, PDFs, or documents. In this post, we’ll walk through how to implement a download endpoint in a Spring Boot REST API.

🎯 What We’re Building

A RESTful endpoint to download a document by ID

Uses Spring Boot’s built-in ResponseEntity and ByteArrayResource

Returns the file as a downloadable attachment with proper headers

🌐 API Design

Method  Endpoint    Description
GET /documents/{id}/download    Download a file by ID

📥 Example HTTP Request
`

`
GET /documents/5/download
✅ Response:
200 OK

Content-Type: application/octet-stream
Content-Disposition: attachment; filename=”document.pdf”
Body: Binary content of the file
`
`

🧑‍💻 Sample Controller Code (Java)

import org.springframework.core.io.ByteArrayResource;
import org.springframework.core.io.Resource;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
public class DocumentController {

    private final DocumentService documentService;

    public DocumentController(DocumentService documentService) {
        this.documentService = documentService;
    }

    @GetMapping("https://dev.to/documents/{id}/download")
    public ResponseEntity downloadDocument(@PathVariable Long id) {
        Document document = documentService.getDocumentById(id);
        ByteArrayResource resource = new ByteArrayResource(document.getData());

        return ResponseEntity.ok()
            .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename="" + document.getFileName() + """)
            .contentType(MediaType.APPLICATION_OCTET_STREAM)
            .body(resource);
    }
}

📦 Required Imports

import org.springframework.core.io.ByteArrayResource;
import org.springframework.core.io.Resource;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

🔐 Security & Best Practices

1. Validate user access before allowing file download
2. Handle file-not-found errors gracefully
3. Support MIME type detection if needed (e.g., application/pdf, image/png)
4. Log download actions for security/auditing
5. Set limits if needed (e.g., download quotas)

💡 Bonus Tips
If files are stored on disk or cloud (like AWS S3), you can stream directly from there

You can enhance UX by connecting this endpoint to a download button on your frontend

Use application-specific MIME types if you want browsers to open the file instead of downloading it

📚 Want to Learn More About MIME Types?
If you’re curious about the full list of commonly used MIME types (for PDFs, images, spreadsheets, and more), check out this resource from MDN Web Docs:

🔗 Common MIME types – MDN Web Docs

✅ Summary
With just a few lines of code, Spring Boot makes it easy to add powerful backend functionality like file downloads. This is especially useful in admin panels, user dashboards, or report-driven systems.

Backend is not just about APIs and databases — it’s about building useful, real-world features that users rely on.