Sending Form Data with Fetch API: In-depth Analysis of FormData and URLSearchParams

Fundamental Characteristics of FormData Objects

In web development, the FormData object serves as a crucial tool for handling form data. According to explicit documentation from MDN, the FormData interface is specifically designed to construct key-value pair collections, but its data format is fixed as multipart/form-data. This means that when developers use FormData as a request body, the browser automatically sets the appropriate content type and boundary identifiers.

In practical usage, many developers encounter this confusion: why does the actual transmitted data remain in multipart/form-data format even when Content-Type: application/x-www-form-urlencoded is explicitly specified in the code? This occurs because the design mechanism of the FormData object dictates that it can only transmit data in multipart/form-data format. The browser ignores manually set content type headers and automatically generates complete request bodies containing random boundary identifiers.

Content Type Conversion Solutions

For scenarios requiring application/x-www-form-urlencoded format data transmission, developers need to adopt alternative approaches. The URLSearchParams interface provides an ideal solution, specifically designed for handling URL-encoded query strings.

The most fundamental implementation involves constructing URLSearchParams by iterating through the FormData object:

const formElement = document.getElementById("form");
const formData = new FormData(formElement);
const urlEncodedData = new URLSearchParams();

for (const [key, value] of formData) {
    urlEncodedData.append(key, value);
}

fetch("api/endpoint", {
    method: "POST",
    body: urlEncodedData,
    headers: {
        "Content-Type": "application/x-www-form-urlencoded"
    }
});

This approach offers complete control over data format while maintaining code clarity and maintainability. It's important to note that when using URLSearchParams as the request body, the browser automatically sets the correct content type header, eliminating the need for manual specification.

Simplified Conversion Methods

Modern browsers provide more concise conversion approaches, allowing direct passing of FormData objects to the URLSearchParams constructor:

const formElement = document.getElementById("form");
const formData = new FormData(formElement);
const urlEncodedData = new URLSearchParams(formData);

fetch("api/endpoint", {
    method: "POST",
    body: urlEncodedData
});

This method significantly simplifies code but requires attention to browser compatibility issues. While most modern browsers support this syntax, thorough compatibility testing remains essential in production environments.

In-depth Data Format Comparison

Understanding the differences between the two data formats is crucial for selecting appropriate solutions. The multipart/form-data format uses boundary identifiers to separate individual fields, making it suitable for transmitting binary data and files. Its format example appears as follows:

---------------------------114782935826962
Content-Disposition: form-data; name="email"

test@example.com
---------------------------114782935826962
Content-Disposition: form-data; name="password"

pw
---------------------------114782935826962--

In contrast, the application/x-www-form-urlencoded format uses simple key-value pair strings, resulting in more compact formatting:

email=test%40example.com&password=pw

This format offers better performance and compatibility when transmitting plain text data, particularly for traditional web application interfaces.

Server-side Processing Recommendations

On the server side, handling data in different content types requires corresponding parsing strategies. For application/x-www-form-urlencoded format, most web frameworks provide built-in parsing support.

Using ASP.NET Core as an example, the [FromForm] attribute can be employed for automatic form data binding:

[HttpPost]
public IActionResult ProcessForm([FromForm] UserCredentials credentials)
{
    // Process form data
    return Ok();
}

public class UserCredentials
{
    public string Email { get; set; }
    public string Password { get; set; }
}

Other server-side frameworks like Express.js, Django, Spring, and others offer similar automatic parsing functionalities, requiring developers to select appropriate processing methods based on their specific technology stacks.

Best Practices Summary

In practical development, selecting appropriate data transmission formats requires consideration of multiple factors. For simple text data submissions, using URLSearchParams with application/x-www-form-urlencoded format is recommended, providing better compatibility and performance. For complex forms containing file uploads, FormData with multipart/form-data format should be used.

Key best practices include:

• Clearly understanding appropriate scenarios for different content types
• Avoiding manual setting of Content-Type headers, allowing browser automatic handling
• Conducting thorough compatibility testing during data format conversion
• Implementing flexible data parsing logic on the server side
• Considering modern form handling libraries to streamline development processes

By deeply understanding the working principles of FormData and URLSearchParams, developers can more flexibly handle various form submission scenarios, building more robust and efficient web applications.