A brief tour of multipart requests

This article was first published in May 2021 and was updated in November 2024.

HTTP is the foundation of today’s internet. Not only is it used to browse webpages, but it’s also used to interact with APIs and even live stream video! HTTP owes its popularity in part to its versatility. It doesn’t matter what kind of content you want to send; HTTP will happily transmit anything. You only need to let the receiver know what kind of data you’re sending by setting a proper Content-Type header.

But what if you need to send data of multiple types in a single request? Say, your cat’s name and picture? This is where multipart content type comes into play.

What is a Multipart Request?

A multipart request is a type of HTTP request that allows sending multiple parts of data in a single request. This format is particularly useful when transferring both binary data (like images, videos, and audio files) and text data. Multipart requests are most commonly used in file uploads, where a client sends one or more files to a server. The multipart format is defined by the multipart/form-data content type, as specified in RFC 2388, which outlines how multipart messages should be structured and interpreted.

Multipart requests are typically used when a client needs to send several files or large files in a single transmission. The key benefits of using multipart requests include:

• Efficiency: Multipart requests allow multiple files to be uploaded in a single HTTP request, reducing the number of network round trips.

• Better error handling: Each part of a multipart request can be processed independently, enabling more granular error handling for each file or data section.

In web development, multipart requests are frequently used to send data from an HTML form to a server. This includes file inputs, where the client can upload files along with other form fields. The server can then parse the request body, extract the individual parts, and process each one accordingly.

Multipart everywhere

The multipart content type is widespread. You might not realize it, but you’ve most likely used it many times in your life.

The most common use for multipart requests is web forms. When you have a form with only text-based input elements — like text inputs, checkboxes, date pickers, etc. — your browser sends that data as an application/x-www-form-urlencoded payload, which essentially means encoding the inputs as key=value pairs. However, as soon as the form contains an input that cannot be encoded as text, such as a file input, the browser uses the multipart/form-data content type.

The other situation where a multipart content type is used is when sending emails with attachments. A regular email is just text, and so it’s sent with text/plain, or sometimes the text/html content type. But PDF or image attachments aren’t text — they’re binary data formats, and so a multipart message is used to send both the email’s text and the attachment.

Anatomy of multipart messages

The syntax of multipart messages is defined in RFC 1521 — MIME, which also defines a couple other content types commonly used on the internet. The RFC defines multiple types of multipart messages (e.g. multipart/mixed), but they all have exactly the same format. Surprisingly, this RFC doesn’t define the multipart/form-data content type, but this content type follows the same specification.

Conceptually, a multipart message is a wrapper around multiple distinct messages. Each part declares its own content type (e.g. application/pdf, image/jpeg), and optionally other metadata. This is what the example HTTP request, sent by — for example — a web browser, looks like:

POST /profile HTTP/1.1
Content-Type: multipart/form-data; boundary=example-part-boundary

--example-part-boundary
Content-Disposition: form-data; name="full_name"
Content-Type: text/plain

Arek Gil
--example-part-boundary
Content-Disposition: form-data; name="profile_picture"; filename="profilepic.jpeg"
Content-Type: image/jpeg

<binary image data>
--customboundary--

When the request is triggered by submitting a form in the browser, you’ll always see that each part declares its name using the Content-Disposition header. The Content-Disposition header may also specify the name of the file if that part should be interpreted as a file attachment.

Security Considerations

When handling multipart requests, security is paramount to prevent potential attacks. One key risk is malicious file uploads, which could be used to exploit server vulnerabilities or compromise sensitive data.

To mitigate this risk:

1. Validate Content Types and File Signatures: Each part of the multipart request should be validated against a whitelist of allowed content types. However, MIME types alone may not be reliable, as they can be spoofed. To strengthen security, analyze file headers or “magic bytes” to ensure files match expected types.

2. Sanitize Filenames to Prevent Path Traversal: The Content-Disposition header specifies filenames for each part of a multipart message, but improper handling can open up path traversal vulnerabilities. Attackers could manipulate filenames to access sensitive files or directories. To prevent this, sanitize filenames by removing directory traversal sequences (e.g., ../). If available, use an F5 iRule or equivalent network inspection to enforce this check at the load balancer level.

3. Limit File and Request Sizes: Set size limits on individual parts and the overall request. This helps prevent denial-of-service (DoS) attacks from overly large uploads that could exhaust server resources.

4. Error Handling for Resilience: Implement robust error handling for multipart requests by isolating errors for each part of the request. This separation ensures that a failure in one part does not affect the entire request processing.

5. Ensure Secure Transmission and Access Control: Always use HTTPS to secure data in transit and enforce authentication and authorization checks before processing multipart requests to ensure that only authorized users can upload files.

By following these security practices, developers can process multipart requests safely, minimizing risks and ensuring efficient handling of uploads.

Multipart in Nutrient products

Multipart messages are useful when transmitting files, and PDF is a file format, so it’s no surprise that we heavily rely on multipart messages in our HTTP-based products, Nutrient Web SDK and Nutrient Document Engine.

Whenever you upload a new document to Nutrient Web SDK (a PDF, an image, or an Office file) or to Document Engine, this is done by sending a file, or by sending that file as a part of the multipart request. The latter option allows you to customize many aspects of document creation, such as setting the title and importing annotations via XFDF.

With Document Engine Build API, you send one or several files and a list of instructions as parts of the multipart request to combine the parts and apply transformations. Or, when you’re using PDF Generation, the generated document’s layout information, the HTML file, and supporting assets are all distinct parts of the same multipart request.

Wrapping up

In this post, we looked at multipart messages: when they’re used, how they look, and how we use them at Nutrient. The multipart format isn’t complicated, and it’s extremely widely used. And so the next time you upload files on the web, it’s likely you’ll be using this format, and you’ll know all about how it works.

FAQ

What is a multipart request used for?

Multipart requests are typically used to send multiple types of data (such as text and files) in a single HTTP request, often for file uploads.

How is multipart content different from other content types?

Multipart content allows you to send different types of data (e.g., text and binary files) in separate parts within the same request, unlike simpler content types like application/x-www-form-urlencoded used for text-only data.

Can multipart requests be used for sending files?

Yes, multipart requests are commonly used for sending files, such as images, videos, and documents, to a server.

What are the security concerns with multipart requests?

The primary security concerns include malicious file uploads, path traversal attacks, and insufficient error handling, which can compromise the server or sensitive data.

How can multipart requests be secured?

Security can be improved by validating file types, sanitizing filenames to prevent path traversal, limiting file sizes, using HTTPS for secure transmission, and implementing robust error handling.