Request Body Examples — Complete Guide

In this tutorial, you will learn about Request Body Examples. We cover key concepts, practical examples, and best practices to help you master this topic.

Request body examples show developers the exact JSON, form data, or binary format to send in an API request, including required and optional fields, nested objects, arrays, proper data types, and the full structure so developers can copy, modify, and send working requests.

What You'll Learn

How to write request body examples that developers can copy and adapt, how to show complete examples with all required and optional fields, how to document nested objects and arrays, how to show different request variations, and how to include expected response alongside the request.

Why It Matters

The request body is where most integration mistakes happen. Developers guess the field names, types, or nesting structure and get 400 errors. A complete, working request body example eliminates this guesswork and gets developers to a successful response faster.

Real-World Use

The DodaTech API documentation shows three request body examples for the compression endpoint: minimal (required fields only), full (all optional fields), and encrypted (with password). Each example includes the response so developers can verify their request worked.

Request Body Structure

flowchart TD
  A[Request Body Example] --> B[Minimal Example]
  A --> C[Full Example]
  A --> D[Variations]
  B --> E[Required fields only]
  C --> F[All fields with realistic data]
  D --> G[Different configurations]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Minimal Request Example

Show the simplest valid request body with only required fields.

#### Minimal Request

The minimum request requires a `file_url` or `file` field.

```json
{
  "file_url": "https://example.com/document.pdf"
}

#### Response

```json
{
  "job_id": "c7f3a2b1-8d4e-4f5a-9b6c-1d2e3f4a5b6c",
  "status": "pending",
  "input_size": 5242880
}

## Complete Request Example

Show the full request body with all optional fields and realistic data.

```markdown
#### Complete Request

This example includes all optional parameters.

```json
{
  "file_url": "https://example.com/report.pdf",
  "format": "zip",
  "level": 9,
  "password": "secure-password-123",
  "metadata": {
    "department": "finance",
    "project": "annual-report-2026"
  }
}

#### Response

```json
{
  "job_id": "d8e4f5a6-9b6c-4f5a-8d4e-1d2e3f4a5b6c",
  "status": "completed",
  "input_size": 5242880,
  "output_size": 1456000,
  "ratio": 0.278,
  "download_url": "https://api.dodatech.com/v2/download/d8e4f5a6"
}

## Multiple Request Variations

Show different configurations to demonstrate the API's capabilities.

```markdown
#### Encryption Example

```json
{
  "file_url": "https://example.com/confidential.pdf",
  "format": "zip",
  "password": "aes-256-encryption-key"
}

#### GZIP Compression Example

```json
{
  "file_url": "https://example.com/application.log",
  "format": "gzip",
  "level": 6
}

#### Direct Upload Example

Use `multipart/form-data` instead of JSON for direct file upload.

```bash
curl -X POST https://api.dodatech.com/v2/files/compress \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@/path/to/document.pdf" \
  -F "format=zip"

## Nested Objects and Arrays

Show how to structure complex nested request bodies.

```markdown
#### Request Body with Nested Objects

```json
{
  "filter": {
    "status": "active",
    "date_range": {
      "start": "2026-01-01",
      "end": "2026-06-30"
    },
    "tags": ["finance", "quarterly"]
  },
  "sort": {
    "field": "created_at",
    "direction": "desc"
  },
  "pagination": {
    "page": 1,
    "per_page": 50
  }
}

## Language-Specific Request Examples

Show the request body in different programming languages.

```python
# Python request
import requests

payload = {
    "file_url": "https://example.com/document.pdf",
    "format": "zip",
    "level": 9
}

response = requests.post(
    "https://api.dodatech.com/v2/files/compress",
    headers={
        "Authorization": "Bearer YOUR_KEY",
        "Content-Type": "application/json"
    },
    json=payload
)

print(response.json())

// JavaScript request
const response = await fetch(
  "https://api.dodatech.com/v2/files/compress",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      fileUrl: "https://example.com/document.pdf",
      format: "zip",
      level: 9,
    }),
  }
);

const data = await response.json();
console.log(data);

Common Mistakes

1. No Request Body Example

Endpoints with request bodies and no examples force developers to guess the format. Every body-requesting endpoint needs at least one example.

2. Only Showing Minimal Example

Showing only required fields without optional fields. Developers may not know about useful optional parameters.

3. Unrealistic Data

Examples with placeholder values like string or 123. Use realistic data that developers can recognize and adapt.

4. No Expected Response

Showing the request without the expected response. Developers cannot verify their request worked without seeing the expected output.

5. Wrong Content Type

Showing JSON example when the endpoint expects form data. Use the correct content type in both the documentation and the code examples.

6. Missing Nested Object Examples

Not showing the structure of nested objects and arrays. Developers must guess the nesting from the parameter table alone.

7. No Variation Examples

Showing one example when the endpoint supports significantly different configurations. Show multiple examples for different use cases.

Practice Questions

1. What three request body examples should every endpoint have?

Minimal (required fields only), complete (all fields with realistic data), and at least one variation showing different configuration options.

2. Why show the expected response after a request example?

The response lets developers verify their request succeeded and shows what the output structure looks like, connecting input to output.

3. How do you document request bodies with nested objects?

Show the complete nested JSON structure with indentation. Explain each level in the parameter table using dot notation: filter.date_range.start.

4. Why include language-specific request examples?

Language-specific examples show developers exactly how to structure the request in their preferred language, including proper headers, Serialization, and error handling.

5. Challenge: Write request body examples for an endpoint that has at least 10 parameters including nested objects and arrays. Show minimal, complete, and two variation examples with expected responses.

FAQ

Mini Project: Request Body Examples

Pick an API endpoint with a complex request body (nested objects, arrays, multiple optional fields). Write minimal, complete, and three variation request body examples with expected responses. Include the raw JSON and language-specific examples in cURL, Python, and JavaScript.

What's Next

Good request examples help developers send correct data. Now learn to document responses with Response Examples. Then explore Writing Error Descriptions.