Request Body Formats in REST API Design — Complete Guide

In this tutorial, you will learn about Request Body Formats in REST API ilink "Api Design" >}}. We cover key concepts, practical examples, and best practices to help you master this topic.

Request body formats define how data is structured when clients send information to REST APIs, with JSON being the most common format, followed by form-data, XML, and binary streams for file uploads.

flowchart TD
  A[Request Body] --> B[JSON]
  A --> C[Form-Data]
  A --> D[XML]
  A --> E[Binary]
  B --> B1[application/json]
  C --> C1[multipart/form-data]
  D --> D1[application/xml]
  E --> E1[application/octet-stream]
  style A fill:#e1f5fe
  style B fill:#c8e6c9

Choose the right Content-Type based on what you are sending. JSON is best for structured data with nested objects. Form-data is needed for file uploads. XML is used in legacy enterprise systems. Binary streams send raw files like images or PDFs.

Think of Content-Type like a label on a shipping box. application/json means the box contains neatly organized items with labels. multipart/form-data means the box has compartments for different types of items including fragile ones. application/octet-stream means the box contains a single raw object.

Example: JSON Request Body

import requests

data = {
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "roles": ["admin", "editor"],
    "profile": {
        "bio": "Full-stack developer",
        "website": "https://alice.dev"
    }
}
response = requests.post(
    "https://api.example.com/users",
    json=data
)
print(f"Content-Type sent: {response.request.headers['Content-Type']}")
print(f"Status: {response.status_code}")

Expected output:

Content-Type sent: application/json
Status: 201

Example: Multipart Form-Data for File Upload

import requests

files = {
    "avatar": ("avatar.jpg", open("avatar.jpg", "rb"), "image/jpeg"),
    "resume": ("resume.pdf", open("resume.pdf", "rb"), "application/pdf")
}
data = {"name": "Bob", "bio": "Developer"}
response = requests.post(
    "https://api.example.com/users/upload",
    files=files,
    data=data
)
print(f"Status: {response.status_code}")
print(f"Uploaded files: {response.json()}")

Expected output:

Status: 201
Uploaded files: {"avatar": "uploads/avatar_42.jpg", "resume": "uploads/resume_42.pdf"}

Example: XML Request Body

import requests

xml_body = """<?xml version="1.0"?>
<user>
    <name>Charlie</name>
    <email>charlie@example.com</email>
    <roles>
        <role>viewer</role>
    </roles>
</user>
"""
headers = {"Content-Type": "application/xml"}
response = requests.post(
    "https://api.example.com/users",
    data=xml_body,
    headers=headers
)
print(f"Status: {response.status_code}")

Expected output:

Status: 201

Common Mistakes

1. Not setting Content-Type header — Without Content-Type, the server may default to the wrong parser and reject valid data or misinterpret the body.
2. Sending JSON as a string instead of structured data — Always let the requests library serialize JSON. Manual Serialization can produce invalid formatting.
3. Using JSON for file uploads — JSON cannot encode binary data efficiently. Use multipart/form-data for files.
4. Sending form-urlencoded for nested data — application/x-www-form-urlencoded does not support nested structures. Use JSON or form-data.
5. Not validating request body size — Accepting arbitrarily large bodies can crash your server. Set limits based on the expected data size.

Practice Questions

1. What Content-Type should you use for file uploads?
2. Why is JSON preferred over XML for most modern REST APIs?
3. What happens if you do not set the Content-Type header?
4. How does multipart/form-data differ from application/json?
5. Challenge: Write a Python script that sends a POST request with a JSON body containing nested objects, arrays, and null values. Then verify the server receives the data correctly by echoing it back.

FAQ

Mini Project

Create a Python script that sends different request body formats (JSON, XML, form-data, binary) to a test API endpoint. For each format, log the Content-Type header sent, the size of the request body, and the server response.

What's Next

Now learn about response formats including JSON and XML in REST API Design.