Page cover

🍊Unit 8: Request Body

Introduction

In FastAPI, the request body is typically used to send data from a client to your API. It is often used for creating or updating resources. FastAPI automatically parses the request body based on the type hints you provide in your function parameters.

FastAPI uses Pydantic models to validate incoming data, ensuring that the request body matches the expected structure and data types. If the validation fails, FastAPI automatically returns a 422 Unprocessable Entity response detailing the validation errors. This greatly simplifies error handling and ensures that your function only processes valid data.

Request Body

Demo 1

Let's implement a simple example of how to define an endpoint that expects a request body in FastAPI:

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None

app = FastAPI()

@app.post("/items/")
async def create_item(item: Item):
    return item

We first declare a data model as a class Item that inherits from BaseModel. You should note that the is_offer is an optional attribute which has a default value is None. The function create_item receive a JSON object from a client and then represented as a dict object in your program.

Since we used Python Type Hints and Pydantic models in the program, we already have data validation. If the data is invalid, the program will return a clear and informative error, indicating exactly where and what the incorrect data is.

To evaluate the program, we use Postman software and create a new POST request to the API endpoint at http://127.0.0.1:8000/items/, as shown in Fig. 1.

Fig. 1. Create a new POST request in Postman software

Demo 2

In this second demonstration program, we will modify the data received from a client and subsequently return the modified data to the client.

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    tax: float = 0.0  # Default value for tax

app = FastAPI()

@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.model_dump()
    if item.tax:
        final_price = item.price + item.tax
        item_dict.update({"final_price": final_price})
    return item_dict

The method item.dict() in class BaseModel is deprecated, use item.model_dump() instead.

We also use Postman software to evaluate the program, as shown in Fig. 2.

Fig. 2. Create a new POST request in Postman software

We can further analyze the program's error scenarios, including cases where the tax is entered as a textual value or when required attributes are missing.

{
    "name": "beer",
    "price": 50000,
    "tax": "five thousand"
}

With the above request body, you will get the following error:

{
    "detail": [
        {
            "type": "float_parsing",
            "loc": [
                "body",
                "tax"
            ],
            "msg": "Input should be a valid number, unable to parse string as a number",
            "input": "five thousand",
            "url": "https://errors.pydantic.dev/2.6/v/float_parsing"
        }
    ]
}

However, you should note that the below request body is correct (tax value is represented as a string) :

{
    "name": "beer",
    "price": 50000,
    "tax": "5000"
}

Demo 3: A complex parameter

In this third demo, we combine all three request body, path parameter and query parameter.

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    tax: float = 0.0  # Default value for tax

app = FastAPI()

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, query: str = None):
    output = {"item_id": item_id, **item.model_dump()}
    if query:
        output.update({"query": query})
    return output

The method item.dict() in class BaseModel is deprecated, use item.model_dump() instead.

To evaluate the program, you should note that:

  • The update_item function now accepts a PUT method, instead of the POST method as in the previous two programs.

  • The item_id is a path parameter.

  • The query is a query parameter.

  • The name, tax, and price are attributes of a request body.

  • The URL to evaluate this API endpoint is http://127.0.0.1:8000/items/1001?query=update-item-price

Fig. 3 and Fig. 4 shows a demonstration of this API endpoint in Postman software.

Fig. 3. Adding Query Parameter in Postman software
Fig. 4. Create a new PUT request in Postman software

Summary

FastAPI provides a powerful and intuitive way to handle request bodies through its seamless integration with Pydantic models. This combination not only ensures that your API endpoints can efficiently parse and validate incoming data but also significantly enhances the developer experience by reducing boilerplate code and automating documentation. By leveraging type hints and Pydantic models, developers can define clear, concise, and self-documenting APIs that enforce data integrity and provide meaningful error messages when data validation fails.

Exercises

1. Create a Student (Body) with Class Path

Scenario: Add a new student to a specific class.

  • Endpoint: POST /classes/{class_id}/students

  • Path params:

    • class_id: int

  • Query params (optional):

    • notify: bool = false — send a welcome email or not

  • Request body (JSON):

    {
    "full_name": "string",
    "email": "string",
    "year": 1
}

  • Tasks:

    1. Define a Pydantic model StudentCreate.

    2. Validate email format and constrain year to 1..4.

    3. Return 201 with created student plus the class_id and notify flag.

  • Example response:

    {
    "class_id": 101,
    "student": {
        "id": 7,
        "full_name": "Jane Doe",
        "email": "[email protected]",
        "year": 1
    },
    "notified": false
}

2. Bulk Insert with Filtering Preview

Scenario: Upload multiple products to a store, with a preview mode.

  • Endpoint: POST /stores/{store_id}/products:bulk

  • Path params:

    • store_id: int

  • Query params:

    • dry_run: bool = true — A dry-run means simulating the action without actually performing it. If true, validate and show what would happen without saving.

    • category: str | None — filter the input to only persist products in this category (when not dry_run)

  • Example URL:

    • POST /stores/101/products:bulk?dry_run=true

    • POST /stores/101/products:bulk?dry_run=false&category=electronics

  • Request body (JSON array):

    [
  { "sku": "ABC-1", "name": "Laptop", "price": 1200.0, "category": "electronics" },
  { "sku": "ABC-2", "name": "Mouse",  "price": 25.0,   "category": "accessories" }
]

  • Tasks:

    1. Define ProductIn model with price > 0.

    2. If dry_run=true, return {"valid": true|false, "errors": [...], "count": N}.

    3. If dry_run=false, save only items matching category (if provided) and return the persisted items.

  • Example dry-run response: 

    { "valid": true, "errors": [], "count": 2 }

3. Partial Update (PATCH) with Field Mask

In HTTP methods, PATCH is used to partially update a resource. Unlike PUT, which requires resubmitting the entire resource, PATCH allows updating only specific fields. In real-world systems (such as e-commerce orders), this is useful when changing delivery notes without altering the status or address, or when updating just the order status (e.g., from processing to shipped). This approach is both more efficient and safer, as it avoids unnecessary overwriting of unchanged data.

Scenario: Partially update an order belonging to a user.

  • Endpoint:

    • PATCH /users/{user_id}/orders/{order_id}

  • Path params:

    • user_id: int, order_id: int

  • Query params (optional):

    • fields: str | None — comma-separated list of fields that are allowed to be updated (e.g., status,shipping_address)

  • Example URL:

    • PATCH /users/55/orders/2001?fields=notes,shipping_address

  • Request body (JSON, all optional fields):

    {
  "status": "processing|shipped|delivered|cancelled",
  "shipping_address": { "street": "string", "city": "string", "zip": "string" },
  "notes": "string | null"
}

  • Tasks:

    1. Create OrderPatch with all fields optional.

    2. If fields is provided, only apply updates to those fields; reject others with 422 and a clear message.

    3. Enforce valid status transitions (e.g., cannot go from delivered → processing).

  • Example response:

    {
    "order_id": 33,
    "updated_fields": [
        "status",
        "notes"
    ],
    "order": {
        "status": "shipped",
        "shipping_address": {
            "street": "19, Nguyen Huu Tho, P. Tan Hung",
            "city": "Ho Chi Minh",
            "zip": "70000"
        },
        "notes": "Leave at door"
    }
}

4. Search + Complex Body Filters + Pagination

limit tells the API how many results to return at most, and offset tells the API how many results to skip before starting to return data.

We use POST in this exercise, instead of GET, because:

  • The filters are too complex for query params.

  • It's more scalable and maintainable.

  • It avoids URL length limits.

Scenario: Search tickets for a given project using complex criteria + pagination.

  • Endpoint: POST /projects/{project_id}/tickets:search

  • Path params:

    • project_id: str

  • Query params:

    • limit: int = 10, offset: int = 0, sort: str = "created_at:desc"

  • Example URL:

    • Returns tickets 6—10 assigned to user u42, sorted by priority ascending: POST /projects/alpha123/tickets:search?limit=5&offset=5&sort=priority:asc

  • Request body (JSON filters):

    {
    "assignees": [
        "u123",
        "u456"
    ],
    "status": [
        "open",
        "in_progress"
    ],
    "created_range": {
        "from": "2025-09-01",
        "to": "2025-09-30"
    },
    "labels": [
        "backend",
        "bug"
    ],
    "text": "database timeout"
}

  • Tasks:

    1. Define nested filter models (DateRange, TicketSearch).

    2. Validate limit in 1..100 and sort format <field>:<asc|desc>.

    3. Apply filters from body, then paginate + sort via query params.

    4. Return total, items, and next_offset if more results exist.

  • Example response:

    {
    "total": 57,
    "items": [
        {
            "id": 901,
            "title": "Fix DB pool",
            "status": "open"
        }
    ],
    "next_offset": 10
}

5*. Idempotent Payments with Idempotency-Key

An Idempotency-Key is a unique identifier (often a UUID) that the client sends with a request to tell the server: "If you receive this same request again with the same key, don’t perform the action twice — just return the same result you gave the first time."

The key benefits of using an Idempotency-Key are that it prevents duplicate operations (such as accidental double-charging), makes APIs more reliable in unstable networks, and improves user experience by removing the risk of unintended repeated actions like pressing "Pay" twice.

Scenario: Process a payment for an invoice with idempotency and mode toggles.

  • Endpoint: POST /invoices/{invoice_id}/payments

  • Path params:

    • invoice_id: str

  • Query params:

    • mode: str = "live" — "test" or "live" controls which ledger to hit

    • retry_on_timeout: bool = true — allow internal retry on gateway timeouts

  • Headers to read (simulate in code):

    • Idempotency-Key: <uuid> — identical requests with the same key must return the same result without double-charging

  • Request body (JSON):

    {
  "method": "card|bank_transfer|wallet",
  "amount": 125.50,
  "currency": "USD",
  "customer": {
    "id": "cus_123",
    "email": "[email protected]"
  },
  "metadata": { "order_id": "ORD-8891" }
}

  • Tasks:

    1. Validate amount > 0, supported currency, and required fields per method.

    2. Respect mode query param to select storage bucket (e.g., in-memory dicts payments_test vs payments_live).

    3. Implement idempotency: if the same Idempotency-Key is seen for the same invoice_id, return the previously stored response.

    4. If retry_on_timeout=true, simulate a transient gateway timeout and an internal retry strategy.

    5. Return normalized payment result with status: succeeded|failed|pending, and echo idempotency_key.

  • Example success response:

    {
  "invoice_id": "INV-1001",
  "payment_id": "pay_77abc",
  "status": "succeeded",
  "amount": 125000.0,
  "currency": "VND",
  "mode": "live",
  "idempotency_key": "8f1a6a57-6e2c-4b7b-8c59-3b5b2b21a1a2",
  "metadata": { "order_id": "ORD-8891" }
}
PreviousUnit 7: Query ParametersNextUnit 9: Query Parameters and Validations

Last updated