Form-Data vs Raw Body

Introduction

When a client sends data to an API, one of the first practical questions is how the request body should be formatted. The endpoint may accept user details, order information, payment instructions, search criteria, a document, an image, or a combination of text fields and files. The client cannot simply send any shape of data and expect the server to understand it. The request must use the format the API contract expects, and the Content-Type header must correctly describe that format.

Two request body formats appear very often in API testing tools such as Postman, REST Assured, Karate, cURL, Swagger UI, browser developer tools, and automation frameworks. These formats are Form-Data and Raw Body. Both send data from a client to a server, but they represent data in different ways and are used for different testing situations. Form-Data sends separate fields, commonly as multipart form-data. Raw Body sends one complete block of content, commonly JSON or XML.

This difference matters because many API failures are not caused by complex server logic. They are caused by sending the right data in the wrong format. A tester may send username and password as form fields when the API expects JSON. Another tester may try to upload a resume by placing the file name inside a JSON string when the API expects multipart form-data. A third tester may set Content-Type as application/json but send XML or plain text. In each case, the request may fail before the business rule is even reached.

Understanding Form-Data vs Raw Body helps API testers build accurate requests, identify contract mismatches, validate negative scenarios, debug 400 Bad Request errors, and explain failures clearly to developers. It is also a common interview topic because it connects HTTP basics, request body design, file upload handling, REST API conventions, and practical API automation.

What Is Form-Data?

Form-Data is a request body format that sends data as individual form fields. Each field has a name and a value, much like an HTML form submitted from a browser. Some fields may contain ordinary text, while other fields may contain file content. In API testing, Form-Data is most commonly associated with the Content-Type multipart/form-data.

A simple definition is this: Form-Data sends data as separate key-value fields, and it is the standard choice when an API needs to receive files along with optional text fields. For example, a profile update API may accept a user's display name, city, and profile picture in the same request. The name and city can be text fields, while the profile picture is a file field. Multipart Form-Data allows those different parts to travel together in one HTTP request.

Form-Data is strongly connected to real web usage. When a user fills a browser form and uploads a resume, profile photo, invoice, or identity proof document, the browser often sends the form using multipart form-data. API clients and automation tools reproduce the same pattern. Instead of manually encoding the whole body as one JSON document, the client adds each field separately and lets the HTTP library generate the multipart structure.

The important point is that multipart form-data is not just a visual table in Postman. Behind the scenes, the request body contains multiple parts separated by boundaries. Each part has headers describing the field name and sometimes the file name and content type. Most tools generate those boundaries automatically. Testers usually do not need to write them by hand, but they should know they exist because missing or incorrect boundaries can break manually constructed multipart requests.

What Is Raw Body?

A Raw Body sends the entire request payload as one complete block of content. That content may be JSON, XML, plain text, HTML, or another format supported by the API. In most REST API testing, Raw Body usually means raw JSON with the Content-Type application/json. In SOAP or XML-based APIs, Raw Body may mean raw XML with the Content-Type application/xml or text/xml.

A simple definition is this: a Raw Body sends the request data as one structured document rather than as separate form fields. The server reads that document and parses it according to the declared Content-Type. If the header says application/json, the server expects valid JSON. If the header says application/xml, the server expects valid XML. If the header says text/plain, the server treats the body as ordinary text.

Raw Body is the preferred style for most modern REST APIs because it represents complex business objects cleanly. A customer registration request, order placement request, payment initiation request, shipment creation request, or loan application request usually contains multiple related fields. Those fields may include nested objects, arrays, booleans, numbers, dates, and optional sections. JSON handles that structure naturally.

Raw Body also makes API contracts easier to document and validate. OpenAPI specifications can define JSON request schemas, required fields, allowed values, numeric ranges, nested object structures, and array rules. Automation tools can load raw JSON templates, modify selected fields, send requests, and validate responses. For XML-based systems, XSD schemas can define the structure and validation rules. In both cases, the body is treated as a structured document.

Form-Data Example

Consider a registration page that collects a name, email address, and profile picture. The request may be represented as Form-Data because it includes a file upload. In a tool such as Postman, the body may appear as a table with three fields:

name          John
email         john@example.com
profilePhoto photo.jpg

The first two fields are text values. The third field is a file. The request header will usually include Content-Type: multipart/form-data, but the full value also includes a generated boundary. The client or tool uses the boundary to separate each part in the HTTP body.

An example request may look conceptually like this:

POST /register HTTP/1.1
Content-Type: multipart/form-data; boundary=----Boundary123

------Boundary123
Content-Disposition: form-data; name="name"

John
------Boundary123
Content-Disposition: form-data; name="email"

john@example.com
------Boundary123
Content-Disposition: form-data; name="profilePhoto"; filename="photo.jpg"
Content-Type: image/jpeg

[binary file content]
------Boundary123--

In daily testing, testers rarely need to type this low-level body manually. Tools build it automatically. Still, understanding this structure explains why multipart requests behave differently from JSON requests. The server receives several independent parts, not one JSON object.

Raw JSON Example

Now consider a user creation API that accepts name and email without a file. This is a strong candidate for Raw JSON. The request body can be sent as one JSON document:

POST /users HTTP/1.1
Content-Type: application/json

{
  "name": "John",
  "email": "john@example.com"
}

Everything is sent as a single payload. The server parses the body as JSON and maps the fields to the expected request model. The payload can be validated for syntax, required fields, data types, string length, email format, duplicate email rules, and business constraints.

This format is simpler for business data because the relationship between fields is clear. If the payload contains an address object, a list of roles, or an array of order items, the raw JSON body can represent that hierarchy directly. Form-Data can also send text fields that look like JSON strings, but that is not the same as sending a native JSON document unless the API explicitly expects that design.

Form-Data Structure

Form-Data consists of multiple independent fields. A field has a name and a value. In multipart form-data, every field is sent as a separate part. A text field may contain a short string such as a name or status. A file field contains file content and usually includes a filename and file-specific content type. This structure is ideal when the API needs to receive binary file content along with small pieces of metadata.

For example, a resume upload API may accept applicant name, job ID, and resume file. The request can be modeled as:

applicantName = John
jobId         = QA-102
resume        = resume.pdf

Each value is separate. The server can read the job ID, process the applicant name, and store the resume file. If the resume is too large, has the wrong extension, has a blocked MIME type, or is missing entirely, the server can return a validation error.

The limitation appears when data becomes deeply structured. Suppose an API needs a customer object with billing address, shipping address, multiple phone numbers, preferences, and item details. Representing that as separate form fields can become awkward and inconsistent. Different teams may use naming conventions such as address.city, address[city], or items[0].sku. Those formats are implementation-specific, so testers must follow the exact API documentation.

Raw Body Structure

Raw Body is one complete document. In JSON, the document may be an object or array. In XML, the document has a root element and nested child elements. The server expects the full document to follow a structure it can parse and validate.

A raw JSON example is:

{
  "name": "John",
  "email": "john@example.com",
  "city": "Chicago"
}

A more complex example may include nested objects and arrays:

{
  "employee": {
    "name": "John",
    "address": {
      "city": "Chicago",
      "state": "IL"
    },
    "skills": ["Java", "API Testing", "SQL"]
  }
}

This type of structure is one of the main reasons raw JSON is widely used in REST APIs. It can represent business meaning directly. The employee has an address, and the employee has a list of skills. A tester can validate each field and relationship without inventing artificial form field names.

Raw XML follows a similar idea using elements and attributes:

<employee>
  <name>John</name>
  <address>
    <city>Chicago</city>
    <state>IL</state>
  </address>
</employee>

The format changes, but the principle remains the same. The body is one structured document, and the server parses it as that document type.

Supported Content Types

Content-Type tells the server how to interpret the request body. Form-Data commonly uses multipart/form-data. Raw JSON uses application/json. Raw XML may use application/xml or text/xml. Plain text uses text/plain. HTML uses text/html. Some APIs also accept specialized content types such as vendor-specific JSON formats.

The body format and Content-Type must match. If a tester sends JSON but sets Content-Type to multipart form-data, the server may try to parse the body as multipart parts and fail. If a tester sends XML but sets Content-Type to application/json, the server may report a JSON parsing error. If the Content-Type is missing, some servers reject the request while others guess the format, which can lead to inconsistent behavior.

In API automation, setting the content type correctly is part of the test setup. Positive tests should use the correct header. Negative tests can intentionally use wrong or missing content types to verify the API returns a clear and controlled error. A well-designed API should not silently accept invalid formats unless that behavior is explicitly documented.

File Upload Handling

File upload is the clearest reason to use Form-Data. When an API needs a real file, multipart form-data is usually the expected format. The request can include both file content and supporting fields. A profile picture upload may include image file, user ID, crop settings, and display preference. A document upload may include PDF file, document type, customer ID, and expiry date. An import API may include a CSV file and import mode.

Raw JSON is not normally used for ordinary file upload because JSON is text-based. A payload such as { "file": "resume.pdf" } sends only a file name, not the file content. The server cannot read the actual PDF from that string unless it has another mechanism to retrieve it. Some APIs accept Base64-encoded file content inside JSON, but that is a different design. It increases payload size and should be used only when the API contract requires it.

Some APIs also support direct binary upload where the raw body is the file itself, often with a content type such as application/pdf or image/png. That is not the same as multipart form-data and not the same as JSON. The endpoint contract decides the correct approach. Testers should verify file name handling, MIME type validation, extension validation, maximum size, empty file behavior, duplicate upload behavior, virus scanning integration where applicable, and error messages.

Data Representation Differences

Form-Data represents data as fields. A username field has a value. A password field has a value. A file field has file content. This representation works well when the request naturally looks like a form submission. It is simple, familiar, and convenient for uploads.

username = john
password = secret

Raw Body represents data as a document. A JSON document can have nested objects and arrays. It can express relationships between fields more naturally than a flat list of form fields.

{
  "username": "john",
  "password": "secret"
}

For simple cases, both may appear similar. For complex business data, the difference becomes significant. A payment request is usually not just separate fields. It may include customer, amount, currency, billing address, payment method, risk flags, and metadata. A shipment request may include sender, receiver, package list, service type, insurance options, and labels. Raw JSON or XML can represent this structure cleanly.

Complex Data and Nested Objects

Complex data is where Raw Body is usually stronger. JSON can naturally represent nested objects, arrays, booleans, nulls, numbers, and strings. XML can naturally represent nested elements, attributes, and repeated structures. Both formats can express a complete business object without flattening it into many artificial field names.

For example, an employee creation API may need address and skill details:

{
  "employee": {
    "name": "John",
    "address": {
      "city": "Chicago",
      "state": "IL"
    },
    "skills": [
      "Java",
      "API Testing"
    ]
  }
}

Representing the same structure in Form-Data depends on the server framework. Some systems may accept employee.name, employee.address.city, and multiple employee.skills fields. Others may expect one field named employee containing a JSON string. Others may reject nested data entirely. This lack of universal structure is why Form-Data is less suitable for deeply nested business requests unless the API documentation is very clear.

For testers, the rule is straightforward: if the API request is primarily structured business data, use Raw Body. If the request is primarily file upload with small supporting fields, use Form-Data. If the API mixes a file and a complex object, read the contract carefully because there are multiple possible designs.

Typical Use Cases

Form-Data is commonly used for file upload, image upload, resume upload, document submission, multipart form submission, importing files, attaching screenshots, uploading reports, and sending a small amount of text along with a file. It is especially useful when a request contains binary content.

Raw Body is commonly used for creating resources, updating resources, sending JSON request objects, SOAP XML requests, search criteria, authentication payloads, payment requests, order placement, address updates, user preference updates, and other business operations. In modern REST APIs, raw JSON is usually the default expectation unless the endpoint is clearly designed for form submission or file upload.

In real projects, both formats may exist in the same application. A user service may accept raw JSON for profile updates, while a document service accepts multipart form-data for uploading identity proof. An order service may accept raw JSON for order creation, while a support ticket service accepts multipart form-data for attachments. Good testers become comfortable with both and choose the format based on the API contract.

Postman Example

In Postman, Form-Data is selected from the Body tab by choosing form-data. The tester then enters rows with key names and values. For each row, the value type can be text or file. If the row is a file, Postman allows the tester to select a local file. Postman generates the multipart request body and boundary automatically.

Body
form-data

name = John        Text
file = image.jpg   File

For Raw Body, the tester selects Body, chooses raw, and then chooses JSON, XML, Text, HTML, or another supported type. If JSON is selected, Postman usually sets the Content-Type to application/json. The request body is entered as one complete block:

{
  "name": "John",
  "city": "Chicago"
}

Postman is useful for learning the difference because the UI makes the request style visible. However, testers should still inspect the generated headers and payload. It is possible to accidentally leave an old Content-Type header, send disabled fields, choose the wrong body type, or save a request in a state that no longer matches the API documentation.

REST Assured Example

REST Assured supports both raw bodies and multipart requests. Raw JSON is usually sent with contentType("application/json") and body():

given()
  .contentType("application/json")
  .body("""
  {
    "name": "John"
  }
  """)
.when()
  .post("/users")
.then()
  .statusCode(201);

Multipart Form-Data can be sent using multiPart():

given()
  .multiPart("file", new File("resume.pdf"))
  .multiPart("name", "John")
.when()
  .post("/upload")
.then()
  .statusCode(200);

The test intent should stay clear. A raw JSON test should validate JSON-specific rules such as missing fields, wrong data types, invalid nested values, and schema violations. A multipart test should validate upload-specific rules such as missing file, empty file, unsupported file type, oversized file, multiple files, and metadata validation.

Karate Example

Karate also supports both styles. Raw JSON can be written directly inside the feature file:

Given request
"""
{
  "name": "John"
}
"""
When method POST
Then status 201

Multipart Form-Data can be expressed using multipart steps:

Given multipart field name = 'John'
And multipart file file = { read: 'resume.pdf', filename: 'resume.pdf' }
When method POST
Then status 200

This makes Karate readable for API testing teams because the request shape is obvious. A reviewer can quickly see whether the scenario is sending a raw JSON payload or a multipart upload. As with other tools, the API contract should drive the body type, not personal preference.

Form-Data vs Raw Body Comparison

The most important difference is structure. Form-Data sends separate key-value fields, while Raw Body sends a single structured document. Form-Data commonly uses multipart/form-data, while Raw Body commonly uses application/json, application/xml, text/plain, or text/html. Form-Data is excellent for file uploads, while Raw Body is excellent for JSON and XML business payloads.

Form-Data can handle files directly. Raw JSON cannot upload a real file simply by writing a file name in the JSON body. Raw Body can represent nested objects and arrays cleanly. Form-Data can represent them only through implementation-specific conventions. Form-Data is often used for forms and uploads. Raw Body is often used for REST and SOAP APIs.

From a testing perspective, Form-Data requires attention to field names, file parts, boundaries, file content types, upload limits, and required metadata. Raw Body requires attention to syntax, schema, data types, nested structure, business validation, security inputs, and response contract accuracy. Both require correct headers and clear negative testing.

API Testing Focus Areas

For Form-Data requests, QA engineers should verify required text fields, missing fields, empty fields, file upload success, invalid file type, maximum file size, zero-byte file behavior, multiple file uploads, duplicate file handling, filename special characters, and server-side validation messages. Security testing should include dangerous file extensions, disguised MIME types, path traversal attempts in file names, and overly large multipart requests.

For Raw Body requests, QA engineers should verify JSON or XML syntax, required fields, optional fields, missing fields, null values, empty strings, wrong data types, nested objects, arrays, invalid enum values, boundary values, duplicate fields where applicable, unknown fields, schema validation, business validation, authorization-sensitive fields, and security payloads. SQL injection, command injection, XML external entity attacks for XML, script injection, and sensitive data exposure should be considered based on the endpoint risk.

Testers should also verify how the API behaves when the body format and Content-Type do not match. For example, send JSON with multipart/form-data, send XML with application/json, send an empty body where a body is required, send a body to an endpoint that should not accept one, and send malformed multipart data. These negative checks help confirm that the API fails safely and predictably.

Common Mistakes

A frequent mistake is sending JSON as Form-Data because the request looks easy to fill as key-value rows in Postman. If the API expects a raw JSON document, separate fields such as name = John and city = Chicago are not equivalent to { "name": "John", "city": "Chicago" }. The server may not bind the values to the expected object.

Another mistake is setting the wrong Content-Type. Sending JSON with Content-Type: multipart/form-data may cause the server to look for multipart boundaries. Sending multipart data with Content-Type: application/json may cause the server to attempt JSON parsing and fail. In automation, this often happens when helper methods reuse headers from a previous request.

Uploading files using raw JSON is also common among beginners. A JSON field containing a file path or file name does not automatically upload the file. Unless the API explicitly expects Base64 content or a reference to an already uploaded file, the request will not contain the real file bytes. For normal upload endpoints, multipart form-data is usually required.

Missing multipart boundaries can also cause confusing failures. Most HTTP clients generate boundaries when the request is built correctly. Problems arise when testers manually set the Content-Type header without allowing the client to add the boundary, or when custom code constructs multipart bodies incorrectly. If a multipart endpoint fails unexpectedly, inspecting the raw HTTP request can reveal whether boundaries and part headers were generated correctly.

Best Practices

Use Raw JSON for most REST APIs that create or update business resources. Use Raw XML for SOAP APIs and XML-based REST APIs. Use Form-Data for file uploads and form-style submissions that include files. Always follow the API documentation rather than guessing from the endpoint name. A URL such as /upload strongly suggests multipart form-data, but the contract is still the final source of truth.

Set the correct Content-Type header for every request. Keep reusable request builders clear so that multipart setup does not accidentally leak into raw JSON tests, and raw JSON headers do not accidentally leak into multipart tests. In automation frameworks, separate helper methods for JSON requests and multipart requests usually reduce confusion.

Validate all fields before sending requests in positive test data, and intentionally vary fields in negative tests. Avoid using Form-Data for complex nested business objects unless the API specifically requires it. Avoid Base64 file upload unless the contract requires it because it increases payload size and can complicate logging and debugging. Keep sensitive data out of logs, especially authentication tokens, passwords, personal identity documents, uploaded files, and payment details.

Real-World Examples

A user registration API that accepts username, password, email, and phone number is usually a Raw JSON request. The payload may be:

{
  "username": "john123",
  "password": "Secret123!",
  "email": "john@example.com"
}

A resume upload API is usually Form-Data because it includes a real file. The request may contain name, job ID, and resume file. A banking transfer API is usually Raw JSON because it represents structured business data such as source account, destination account, amount, currency, and transfer note. A profile picture upload API is usually Form-Data because the important content is an image file.

A SOAP payment inquiry API may use Raw XML. A log ingestion API may accept Raw JSON arrays or newline-delimited text depending on the contract. A bulk import API may use multipart form-data to upload a CSV file, while a bulk update API may use Raw JSON to submit an array of records. Real projects rarely use one format everywhere, so testers must read each endpoint contract carefully.

Interview Questions

A common interview question is: what is Form-Data? A strong answer is that Form-Data is a request body format that sends data as individual key-value fields and is commonly used for file uploads. With multipart/form-data, each field is sent as a separate part, and file fields can include actual file content.

Another question is: what is a Raw Body? A Raw Body sends the entire request payload as a single document, such as JSON, XML, plain text, or HTML. In REST API testing, raw JSON is very common because it supports structured business data, nested objects, arrays, and clear schema validation.

Interviewers may also ask when Form-Data should be used. The practical answer is: use Form-Data when uploading files or sending form-style fields that include files. When asked when Raw JSON should be used, the answer is: use Raw JSON when sending structured business data to REST APIs, especially create and update operations.

A deeper interview question is what happens when the wrong Content-Type is used. The server may parse the body incorrectly, reject the request, return a 400 or 415 error, ignore fields, or produce validation errors. A tester should verify that the API handles wrong content types safely and returns useful error messages.

Interview-Ready Explanation

Form-Data and Raw Body are two different request body formats used in HTTP APIs. Form-Data sends data as individual key-value fields, commonly using the multipart/form-data content type. It is mainly used for file uploads, image uploads, resume uploads, and HTML form-style submissions where files and text fields may be sent together. Multipart requests divide the body into separate parts, and each part can represent a text field or file field.

Raw Body sends the entire request payload as one structured document. In REST APIs, this is usually JSON with application/json. In SOAP or XML-based APIs, it may be XML with application/xml or text/xml. Raw Body is preferred for most business operations because it can represent complex nested objects, arrays, data types, and complete request models clearly.

The key testing rule is to use the format expected by the API contract. Use Form-Data for file uploads and multipart submissions. Use Raw JSON or Raw XML for structured request payloads. Set the correct Content-Type header, validate required fields and business rules, and include negative tests for wrong formats, missing headers, malformed bodies, and invalid data. Choosing the wrong body format can cause request parsing failures before the API reaches business validation.

Key Takeaway

Form-Data and Raw Body solve different API request problems. Form-Data is field-based and is strongest when files must be uploaded. Raw Body is document-based and is strongest when structured business data must be sent as JSON, XML, or another complete payload format. They are not interchangeable unless the API explicitly supports both.

The practical rule is simple: use Raw JSON for most REST business requests, Raw XML for XML or SOAP requests, and Form-Data for file upload requests. Always verify Content-Type, request structure, required fields, validation rules, and negative behavior. A tester who understands this difference can build cleaner API tests, debug request failures faster, and avoid one of the most common causes of API testing confusion.