A Comprehensive Guide to Sending multipart/form-data Files with Angular $http

Problem Context and Common Misconceptions

File upload is a common requirement in web development, particularly when sending files in multipart/form-data format. Developers using Angular's $http service often encounter issues with Content-Type configuration. Common misconceptions include:

• Setting Content-Type to undefined, which causes the browser to auto-detect file types (e.g., image/png) instead of generating multipart/form-data format
• Manually setting Content-Type: multipart/form-data, which fails due to missing boundary parameters

These problems stem from insufficient understanding of the multipart/form-data format, which requires a unique boundary string to separate form fields, typically auto-generated by HTTP clients.

Core Solution: The FormData Object

HTML5 introduced the FormData API specifically for constructing form data, including file uploads. In AngularJS, the correct implementation is:

this.uploadFileToUrl = function(file, uploadUrl) {
    var fd = new FormData();
    fd.append('file', file);
    
    $http.post(uploadUrl, fd, {
        transformRequest: angular.identity,
        headers: {'Content-Type': undefined}
    })
    .success(function(response) {
        // Handle success
    })
    .error(function(error) {
        // Handle error
    });
}

Key aspects:

1. FormData Creation: Use new FormData() to create the form data object and add files via append()
2. transformRequest Configuration: transformRequest: angular.identity instructs Angular not to transform the data, preserving the FormData object's original state
3. Content-Type Handling: Setting Content-Type to undefined allows the browser to auto-set the correct multipart/form-data header with necessary boundary parameters

Updated Implementation for Angular 4/5

In Angular 4 and later versions, the API has evolved:

import { HttpClient } from '@angular/common/http';

uploadFileToUrl(files, restObj, uploadUrl): Promise<any> {
    const formData = new FormData();
    
    // Add files
    for (const file of files) {
        formData.append(file.name, file);
    }
    
    // Optional: Add other form data
    Object.keys(restObj).forEach(key => {
        formData.append(key, restObj[key]);
    });
    
    // Important: Do not set Content-Type header
    const options = {} as any;
    
    return this.httpClient.post(uploadUrl, formData, options)
        .toPromise()
        .catch((error) => {
            // Error handling
        });
}

Major changes:

• HttpClient replaces the original Http service
• transformRequest and angular.identity are removed; FormData is now handled automatically
• Capability to upload files alongside other form data

Technical Details and Considerations

Boundary Parameter Generation: When using FormData, browsers automatically generate boundary strings like "----WebKitFormBoundary7MA4YWxkTrZu0gW" and correctly set the Content-Type header.

Server-Side Compatibility: Some server-side parsers (e.g., multer in Express) rely on browser-auto-set Content-Type headers. Manually setting Content-Type: multipart/form-data may break these parsers as they require complete boundary information.

Multiple File Uploads: Multiple files can be added to the same FormData object via iteration, using different or identical field names depending on server-side implementation.

Best Practices Summary

1. Always use FormData objects for file uploads
2. Let the browser auto-set Content-Type headers (set to undefined or omit)
3. In AngularJS, use transformRequest: angular.identity to preserve data format
4. In Angular 4+, HttpClient automatically handles FormData
5. Avoid manually setting multipart/form-data Content-Type unless fully understanding boundary parameter mechanisms
6. Test considering potential variations in FormData implementation across browsers

By adhering to these principles, developers can avoid common file upload pitfalls and implement stable, reliable multipart form data submission functionality.