← Request Handling & Response Models

Select a question from the sidebar

18 questions in this topic

Question 1 / 18

How do you accept JSON request bodies using Pydantic models?

FastAPI automatically parses JSON request bodies into Pydantic models when you declare a parameter with a Pydantic model type. The framework inspects the function signature, sees the Pydantic type, and reads the request body as JSON, validates it against the model, and passes the validated object to your handler.

How it works:

Client sends a POST/PUT/PATCH request with a JSON body
FastAPI reads the raw body and parses it as JSON
The JSON dict is passed to the Pydantic model constructor
Pydantic validates all fields (types, constraints, custom validators)
If validation fails, FastAPI returns a 422 Unprocessable Entity with detailed error messages
If validation passes, your function receives a typed Python object

Key features:

Automatic type coercion: strings that look like numbers are coerced where safe
Default values: fields with defaults become optional in the request
Nested models: Pydantic models can contain other Pydantic models
JSON Schema: the model auto-generates the request body schema in Swagger docs

Validation errors:

When validation fails, FastAPI returns a structured 422 response with detail containing an array of error objects, each specifying the field location, message, and error type.

Pseudo Code

# Declare a Pydantic model
class ItemCreate(BaseModel):
    name: string (required)
    price: float (must be > 0)
    tags: list of strings (defaults to empty)

# Use it as a parameter type
@app.POST("/items/")
function create_item(item: ItemCreate):
    # item is already validated
    # Access fields: item.name, item.price, item.tags
    return item as dict

Code

from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI()

class ItemCreate(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0)
    description: str | None = None
    tags: list[str] = []

@app.post("/items/", status_code=201)
def create_item(item: ItemCreate):
    """item is auto-parsed from the JSON request body."""
    return {"item": item.model_dump(), "message": "created"}

client = TestClient(app)

# Valid JSON body
response = client.post("/items/", json={
    "name": "Widget",
    "price": 9.99,
    "tags": ["sale"]
})
print("Valid:", response.status_code, response.json())

# Missing required field
response = client.post("/items/", json={"price": 9.99})
print("Missing name:", response.status_code)

# Invalid type
response = client.post("/items/", json={"name": "Widget", "price": "free"})
print("Bad type:", response.status_code)

Valid: 201 {'item': {'name': 'Widget', 'price': 9.99, 'description': None, 'tags': ['sale']}, 'message': 'created'}
Missing name: 422
Bad type: 422

Key Points

•Declare a Pydantic model as a function parameter and FastAPI auto-parses the JSON body into it
•Validation failures return 422 with detailed error messages listing every invalid field
•Fields with default values are optional in the request body
•The Pydantic model auto-generates the request body schema in Swagger UI docs

Gotchas

•A parameter typed as a Pydantic model is always read from the request body, not from query or path
•FastAPI attempts to parse the body as JSON regardless of Content-Type for Pydantic model parameters -- a missing or non-parseable body causes a 422 validation error
•Pydantic v2 is stricter by default -- 'true' (string) won't coerce to True (bool) unless you configure it

Declare a Pydantic model as a parameter type and FastAPI automatically reads the JSON body, validates it, and passes the typed object to your handler. Invalid data returns 422 with detailed errors.

•Pydantic model parameter = auto-parsed JSON body with full validation

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float
    tags: list[str] = []

@app.post("/items/")
def create_item(item: Item):  # auto-parsed from JSON body
    return item.model_dump()

Missing or invalid fields return 422, not 400 -- this is by design per OpenAPI spec

Question 2 / 18

How do you handle Form data in FastAPI?

FastAPI handles HTML form data (application/x-www-form-urlencoded) using the Form() function. Unlike JSON bodies that use Pydantic models directly, form fields are declared as individual function parameters annotated with Form().

How it works:

Import Form from fastapi
Declare each form field as a parameter with Form() as its default
FastAPI reads the form-encoded body and extracts each field
Type validation still applies (e.g., int fields must be numeric)

Why Form is separate from Body:

Form data uses a different encoding (application/x-www-form-urlencoded or multipart/form-data) than JSON (application/json). FastAPI needs to know the encoding format to parse correctly.

Common use cases:

Login forms (username/password)
HTML form submissions
OAuth2 password flow (requires Form fields per spec)
Legacy API compatibility

Annotated syntax (recommended):

Use Annotated[str, Form()] for cleaner type hints that work better with editors and type checkers.

Pseudo Code

# Form data uses Form() instead of Body()
from fastapi import Form

@app.POST("/login/")
function login(
    username: string = Form(),   # Required form field
    password: string = Form(),   # Required form field
    remember: bool = Form(False) # Optional with default
):
    # Fields parsed from form-encoded body
    # NOT from JSON
    return {username, remember}

Code

from typing import Annotated
from fastapi import FastAPI, Form
from fastapi.testclient import TestClient

app = FastAPI()

# Using Annotated syntax (recommended)
@app.post("/login/")
def login(
    username: Annotated[str, Form()],
    password: Annotated[str, Form()],
    remember_me: Annotated[bool, Form()] = False,
):
    # password would be hashed in real code
    return {"username": username, "remember_me": remember_me}

# Form with validation
@app.post("/register/")
def register(
    username: Annotated[str, Form(min_length=3, max_length=50)],
    email: Annotated[str, Form()],
    age: Annotated[int, Form(ge=13)],
):
    return {"username": username, "email": email, "age": age}

client = TestClient(app)

# Send form data (not JSON)
response = client.post("/login/", data={
    "username": "alice",
    "password": "secret123",
    "remember_me": "true"
})
print("Login:", response.json())

response = client.post("/register/", data={
    "username": "bob",
    "email": "bob@example.com",
    "age": "25"
})
print("Register:", response.json())

Login: {'username': 'alice', 'remember_me': True}
Register: {'username': 'bob', 'email': 'bob@example.com', 'age': 25}

Key Points

•Use Form() to declare form fields -- they read from application/x-www-form-urlencoded, not JSON
•Each form field is a separate function parameter, unlike JSON bodies which use Pydantic models
•Annotated[str, Form()] is the recommended modern syntax for form parameters
•Form fields support the same validation constraints as Query and Path (min_length, ge, etc.)

Gotchas

•python-multipart must be installed for Form to work -- pip install python-multipart (included in fastapi[standard])
•You cannot mix Form() and Body() in the same endpoint -- they use different content types
•Form data sends all values as strings -- FastAPI coerces '25' to int, 'true' to bool automatically

Use Form() to read HTML form data. Each form field is a separate parameter annotated with Form(). Unlike JSON bodies, form data uses application/x-www-form-urlencoded encoding.

•Form() reads form-encoded data, not JSON -- each field is a separate parameter

from typing import Annotated
from fastapi import FastAPI, Form

app = FastAPI()

@app.post("/login/")
def login(
    username: Annotated[str, Form()],
    password: Annotated[str, Form()],
):
    return {"username": username}

Requires python-multipart package -- pip install python-multipart

Question 3 / 18

How do you handle file uploads with File and UploadFile?

FastAPI provides two ways to handle file uploads:

1. `bytes` with `File()`

Reads the entire file into memory as bytes. Simple but only suitable for small files.

2. `UploadFile`

A file-like object that uses spooled temporary files. The file is kept on disk if it exceeds a size threshold, making it suitable for large files.

UploadFile attributes:

filename -- original filename from the client
content_type -- MIME type (e.g., image/png)
file -- the underlying SpooledTemporaryFile
size -- file size in bytes

UploadFile async methods:

await file.read(size) -- read bytes
await file.write(data) -- write bytes
await file.seek(offset) -- move position
await file.close() -- close the file

Content type:

File uploads use multipart/form-data encoding. You can combine file uploads with form fields in the same endpoint.

Annotated syntax:

Use Annotated[UploadFile, File()] for the recommended modern style.

Pseudo Code

# Small files -- reads entire file into memory
@app.POST("/upload-bytes/")
function upload(file: bytes = File()):
    size = length(file)
    return {size}

# Large files -- spooled to disk
@app.POST("/upload/")
function upload(file: UploadFile):
    contents = await file.read()
    filename = file.filename
    content_type = file.content_type
    return {filename, size, content_type}

Code

from typing import Annotated
from fastapi import FastAPI, File, UploadFile
from fastapi.testclient import TestClient

app = FastAPI()

# Method 1: bytes -- entire file in memory (small files only)
@app.post("/upload-bytes/")
def upload_bytes(file: Annotated[bytes, File()]):
    return {"size": len(file)}

# Method 2: UploadFile -- spooled to disk for large files
@app.post("/upload/")
async def upload_file(file: UploadFile):
    contents = await file.read()
    return {
        "filename": file.filename,
        "content_type": file.content_type,
        "size": len(contents),
    }

# Combine file upload with form fields
@app.post("/upload-with-meta/")
async def upload_with_metadata(
    file: UploadFile,
    description: Annotated[str, Form()] = "No description",
):
    contents = await file.read()
    return {
        "filename": file.filename,
        "description": description,
        "size": len(contents),
    }

client = TestClient(app)

# Upload as bytes
response = client.post(
    "/upload-bytes/",
    files={"file": ("test.txt", b"Hello, World!", "text/plain")}
)
print("Bytes:", response.json())

# Upload as UploadFile
response = client.post(
    "/upload/",
    files={"file": ("report.pdf", b"PDF content here", "application/pdf")}
)
print("UploadFile:", response.json())

Bytes: {'size': 13}
UploadFile: {'filename': 'report.pdf', 'content_type': 'application/pdf', 'size': 16}

Key Points

•bytes with File() loads the entire file into memory -- use only for small files
•UploadFile spools large files to disk and provides filename, content_type, and async read/write methods
•File uploads use multipart/form-data encoding and can be combined with Form fields
•Use await file.read() to get contents, file.filename for the original name

Gotchas

•python-multipart must be installed for file uploads to work
•UploadFile.read() is async -- use 'await' in async def handlers or use file.file.read() in sync handlers
•UploadFile does not validate file type or size -- you must check content_type and size manually

Use UploadFile for file uploads -- it spools large files to disk and provides filename, content_type, and async read(). Use bytes with File() only for small files that fit in memory.

•UploadFile handles large files via disk spooling; bytes loads everything into memory

from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/upload/")
async def upload(file: UploadFile):
    contents = await file.read()
    return {"filename": file.filename, "size": len(contents)}

You must validate file type and size yourself -- UploadFile does not enforce limits

Question 4 / 18

What is response_model and how does it filter response data?

response_model is a decorator parameter that tells FastAPI to filter and validate the response through a Pydantic model before sending it to the client.

What response_model does:

Filters fields: Only fields defined in the response model are included in the output
Validates types: Ensures the response conforms to the declared schema
Generates docs: Adds the response schema to OpenAPI/Swagger documentation
Serializes: Converts Python objects (datetime, UUID, etc.) to JSON-compatible types

Why it matters:

You often have internal data with sensitive fields (passwords, internal IDs) that should never be sent to clients. response_model acts as a security filter, ensuring only the declared fields are exposed.

How filtering works:

Your handler can return a dict, Pydantic model, ORM object, or any object with matching attributes
FastAPI passes the return value through the response model
Fields not in the response model are silently dropped
Missing required fields raise a server error

Return type annotation vs response_model:

FastAPI also supports -> ItemResponse return type annotations for response filtering, but response_model in the decorator takes precedence and is more explicit.

Pseudo Code

# Internal model has sensitive data
class UserDB:
    id, name, email, hashed_password, is_admin

# Response model exposes only safe fields
class UserResponse:
    id, name, email

@app.GET("/users/{id}", response_model=UserResponse)
function get_user(id):
    user = db.get(id)
    return user  # FastAPI filters out hashed_password and is_admin
    # Client only sees: {id, name, email}

Code

from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel

app = FastAPI()

# Full internal model
class UserInDB(BaseModel):
    id: int
    name: str
    email: str
    hashed_password: str
    is_admin: bool

# Public response model -- no sensitive fields
class UserResponse(BaseModel):
    id: int
    name: str
    email: str

# response_model filters the output
@app.get("/users/{user_id}", response_model=UserResponse)
def get_user(user_id: int):
    # Return full internal model -- response_model strips sensitive fields
    return UserInDB(
        id=user_id,
        name="Alice",
        email="alice@example.com",
        hashed_password="$2b$12$secrethash",
        is_admin=True,
    )

# Without response_model -- everything is exposed
@app.get("/users-unsafe/{user_id}")
def get_user_unsafe(user_id: int):
    return {
        "id": user_id,
        "name": "Alice",
        "email": "alice@example.com",
        "hashed_password": "$2b$12$secrethash",
    }

client = TestClient(app)

safe = client.get("/users/1").json()
print("Safe:", safe)
print("Has password:", "hashed_password" in safe)

unsafe = client.get("/users-unsafe/1").json()
print("Unsafe has password:", "hashed_password" in unsafe)

Safe: {'id': 1, 'name': 'Alice', 'email': 'alice@example.com'}
Has password: False
Unsafe has password: True

Key Points

•response_model filters the response to only include fields defined in the Pydantic model
•It prevents sensitive data (passwords, internal flags) from leaking to clients
•It also generates the response schema in Swagger/OpenAPI docs
•You can return any object with matching attributes -- dicts, ORM objects, or Pydantic models

Gotchas

•Without response_model, ALL fields in your return value are sent to the client -- including sensitive data
•response_model in the decorator takes precedence over the function's return type annotation
•If the return value is missing a required field in response_model, FastAPI raises a 500 server error, not 422

response_model filters your handler's return value through a Pydantic model, stripping out any fields not in the schema. It prevents sensitive data from leaking and generates the response schema in docs.

•response_model filters output fields and generates docs schema

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class UserOut(BaseModel):
    id: int
    name: str

@app.get("/users/{uid}", response_model=UserOut)
def get_user(uid: int):
    # password is stripped by response_model
    return {"id": uid, "name": "Alice", "password": "secret"}

Without response_model, all returned fields are exposed -- including sensitive data

Question 5 / 18

How do you set HTTP status codes in responses?

FastAPI provides multiple ways to set HTTP status codes:

1. Decorator parameter (default status code)

Set the default status code in the route decorator. This is the most common approach.

2. `status` module constants

FastAPI re-exports Starlette's status module with named constants for all standard HTTP codes. This improves readability and catches typos at import time.

3. `Response` parameter (dynamic status code)

Inject a Response object to change the status code dynamically at runtime.

4. Raise `HTTPException`

Raise an exception with a specific status code for error cases.

5. Return a `Response` directly

Return a JSONResponse, HTMLResponse, etc. with a custom status code.

Common status codes:

Code	Constant	Meaning
200	HTTP_200_OK	Default for GET
201	HTTP_201_CREATED	Resource created
204	HTTP_204_NO_CONTENT	Success, no body
400	HTTP_400_BAD_REQUEST	Client error
404	HTTP_404_NOT_FOUND	Not found
422	HTTP_422_UNPROCESSABLE_ENTITY	Validation error

Pseudo Code

# Method 1: Default in decorator
@app.POST("/items/", status_code=201)
function create_item(item):
    return item  # Always returns 201

# Method 2: Dynamic via Response parameter
@app.PUT("/items/{id}")
function update(id, item, response: Response):
    if exists(id):
        response.status_code = 200  # Updated
    else:
        response.status_code = 201  # Created
    return item

# Method 3: Error via HTTPException
if not found:
    raise HTTPException(status_code=404, detail="Not found")

Code

from fastapi import FastAPI, HTTPException, Response, status
from fastapi.testclient import TestClient
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str

items_db: dict[int, dict] = {}

# Method 1: Default status code in decorator
@app.post("/items/", status_code=status.HTTP_201_CREATED)
def create_item(item: Item):
    items_db[1] = item.model_dump()
    return {"id": 1, **item.model_dump()}

# Method 2: Dynamic status code via Response parameter
@app.put("/items/{item_id}")
def upsert_item(item_id: int, item: Item, response: Response):
    if item_id in items_db:
        response.status_code = status.HTTP_200_OK
    else:
        response.status_code = status.HTTP_201_CREATED
    items_db[item_id] = item.model_dump()
    return {"id": item_id, **item.model_dump()}

# Method 3: HTTPException for errors
@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id not in items_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Item {item_id} not found",
        )
    return items_db[item_id]

# Method 4: No content response
@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_item(item_id: int):
    items_db.pop(item_id, None)

client = TestClient(app)

# 201 Created
resp = client.post("/items/", json={"name": "Widget"})
print(f"Create: {resp.status_code}")

# 404 Not Found
resp = client.get("/items/99")
print(f"Not found: {resp.status_code} {resp.json()['detail']}")

# 204 No Content
resp = client.delete("/items/1")
print(f"Delete: {resp.status_code}")

Create: 201
Not found: 404 Item 99 not found
Delete: 204

Key Points

•Set default status code with status_code parameter in the route decorator
•Use status.HTTP_201_CREATED constants for readability instead of magic numbers
•Inject Response parameter to change status code dynamically at runtime
•Raise HTTPException for error status codes with detail messages

Gotchas

•status_code=204 (No Content) means the response body is empty -- do not return data with 204
•The default status code is 200 for all methods if not specified -- POST endpoints should explicitly set 201
•HTTPException detail is included in the response JSON body -- do not put sensitive info in it

Set the default status code in the decorator with status_code=201, use status.HTTP_201_CREATED constants for readability, inject Response for dynamic codes, or raise HTTPException for errors.

•Decorator status_code for defaults, HTTPException for errors, Response for dynamic codes

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

@app.post("/items/", status_code=status.HTTP_201_CREATED)
def create_item():
    return {"id": 1}

@app.get("/items/{item_id}")
def get_item(item_id: int):
    raise HTTPException(status_code=404, detail="Not found")

Default is 200 for all methods -- set 201 explicitly for POST creation endpoints

Question 6 / 18

What is the difference between JSONResponse, HTMLResponse, and PlainTextResponse?

FastAPI provides several response classes (inherited from Starlette) for returning different content types:

JSONResponse (default)

Content-Type: application/json
Serializes Python dicts/lists to JSON
This is what FastAPI uses automatically when you return a dict or Pydantic model
Supports custom headers and status codes

HTMLResponse

Content-Type: text/html
Returns raw HTML strings
Used for server-rendered pages or HTML fragments
Set via response_class=HTMLResponse in the decorator

PlainTextResponse

Content-Type: text/plain
Returns raw text without any formatting
Useful for health checks, simple status endpoints, or text-based APIs

How to use them:

Return directly: Return a response class instance from your handler
Set response_class: Use the decorator parameter to change the default for that endpoint
Override per-request: Always return a specific response class instance

Other useful response classes:

RedirectResponse -- HTTP redirects
StreamingResponse -- streaming large data
FileResponse -- serving files
ORJSONResponse -- faster JSON with orjson library

Pseudo Code

# JSONResponse -- default, no special handling needed
@app.GET("/data")
function get_data():
    return {"key": "value"}  # Auto-wrapped in JSONResponse

# HTMLResponse -- set response_class
@app.GET("/page", response_class=HTMLResponse)
function get_page():
    return "<h1>Hello</h1>"  # Content-Type: text/html

# PlainTextResponse -- set response_class
@app.GET("/health", response_class=PlainTextResponse)
function health():
    return "OK"  # Content-Type: text/plain

# Direct return -- always works
@app.GET("/custom")
function custom():
    return JSONResponse(content={...}, status_code=201, headers={...})

Code

from fastapi import FastAPI
from fastapi.responses import (
    JSONResponse, HTMLResponse, PlainTextResponse, RedirectResponse
)
from fastapi.testclient import TestClient

app = FastAPI()

# JSONResponse -- default behavior
@app.get("/api/data")
def get_data():
    return {"message": "This is JSON"}  # Auto JSONResponse

# HTMLResponse via response_class
@app.get("/page", response_class=HTMLResponse)
def get_page():
    return """
    <html>
        <body><h1>Hello from FastAPI</h1></body>
    </html>
    """

# PlainTextResponse
@app.get("/health", response_class=PlainTextResponse)
def health_check():
    return "OK"

# Direct return with custom status and headers
@app.get("/custom")
def custom_response():
    return JSONResponse(
        content={"status": "created"},
        status_code=201,
        headers={"X-Custom": "header-value"},
    )

# Redirect
@app.get("/old-page")
def old_page():
    return RedirectResponse(url="/page")

client = TestClient(app)

resp = client.get("/api/data")
print(f"JSON: {resp.headers['content-type']} -> {resp.json()}")

resp = client.get("/page")
print(f"HTML: {resp.headers['content-type']}")

resp = client.get("/health")
print(f"Text: {resp.headers['content-type']} -> {resp.text}")

resp = client.get("/custom")
print(f"Custom: {resp.status_code} X-Custom={resp.headers['x-custom']}")

JSON: application/json -> {'message': 'This is JSON'}
HTML: text/html; charset=utf-8
Text: text/plain; charset=utf-8 -> OK
Custom: 201 X-Custom=header-value

Key Points

•JSONResponse is the default -- returning a dict auto-wraps it in JSONResponse
•HTMLResponse sets Content-Type to text/html for server-rendered pages
•PlainTextResponse sets Content-Type to text/plain for simple text output
•Return a response class instance directly for full control over status, headers, and content

Gotchas

•response_class=HTMLResponse disables response_model validation -- FastAPI trusts your raw HTML string
•When returning a Response instance directly, FastAPI skips jsonable_encoder -- you handle serialization
•ORJSONResponse requires the orjson package but is significantly faster for large JSON payloads

JSONResponse (default) returns application/json, HTMLResponse returns text/html, and PlainTextResponse returns text/plain. Set via response_class in the decorator or return an instance directly for custom status/headers.

•JSONResponse is default; use response_class to switch to HTML or PlainText

from fastapi import FastAPI
from fastapi.responses import HTMLResponse, PlainTextResponse

app = FastAPI()

@app.get("/")  # default JSONResponse
def json_endpoint():
    return {"msg": "JSON"}

@app.get("/page", response_class=HTMLResponse)
def html_endpoint():
    return "<h1>HTML</h1>"

@app.get("/health", response_class=PlainTextResponse)
def text_endpoint():
    return "OK"

response_class=HTMLResponse disables response_model validation

Question 7 / 18

How do you use StreamingResponse for large data?

StreamingResponse sends data to the client in chunks rather than loading the entire response into memory. This is essential for large files, real-time data, or dynamically generated content.

How it works:

You provide a generator (sync or async) that yields chunks of data
FastAPI/Starlette sends each chunk as it is yielded
The client receives data progressively
Memory usage stays constant regardless of total data size

When to use StreamingResponse:

Large files: CSV exports, logs, reports
Real-time data: Server-Sent Events (SSE)
Dynamic generation: Content generated on-the-fly
Proxying: Forwarding data from another service

Parameters:

content -- a generator, async generator, or iterable
media_type -- Content-Type header (e.g., text/csv, text/event-stream)
headers -- custom response headers
status_code -- HTTP status (default 200)

For file downloads:

Use FileResponse for static files. Use StreamingResponse when the content is generated dynamically or read from another source.

Pseudo Code

# Streaming large data
@app.GET("/download-csv")
function download_csv():
    def generate_rows():
        yield "header1,header2\n"
        for row in database.query_all():
            yield f"{row.col1},{row.col2}\n"
    
    return StreamingResponse(
        content=generate_rows(),
        media_type="text/csv",
        headers={"Content-Disposition": "attachment; filename=data.csv"}
    )

Code

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from fastapi.testclient import TestClient
import io

app = FastAPI()

# Stream a large CSV dynamically
@app.get("/download-csv")
def download_csv():
    def generate():
        yield "id,name,price\n"
        for i in range(1, 101):  # Could be millions of rows
            yield f"{i},Item {i},{i * 9.99:.2f}\n"

    return StreamingResponse(
        content=generate(),
        media_type="text/csv",
        headers={"Content-Disposition": "attachment; filename=items.csv"},
    )

# Stream from a file-like object
@app.get("/download-report")
def download_report():
    buffer = io.BytesIO(b"Report content here...")
    return StreamingResponse(
        content=buffer,
        media_type="application/octet-stream",
        headers={"Content-Disposition": "attachment; filename=report.bin"},
    )

# Async generator streaming
@app.get("/stream-events")
async def stream_events():
    async def event_generator():
        for i in range(5):
            yield f"data: event {i}\n\n"

    return StreamingResponse(
        content=event_generator(),
        media_type="text/event-stream",
    )

client = TestClient(app)

# Download CSV
resp = client.get("/download-csv")
lines = resp.text.strip().split("\n")
print(f"CSV lines: {len(lines)} (header + 100 rows)")
print(f"First line: {lines[0]}")
print(f"Content-Disposition: {resp.headers['content-disposition']}")

CSV lines: 101 (header + 100 rows)
First line: id,name,price
Content-Disposition: attachment; filename=items.csv

Key Points

•StreamingResponse sends data in chunks using a generator -- constant memory usage for any data size
•Pass a sync generator, async generator, or file-like object as the content parameter
•Set media_type for correct Content-Type and Content-Disposition for file downloads
•Use for large CSV exports, real-time SSE streams, or dynamically generated content

Gotchas

•StreamingResponse does not set Content-Length -- the client does not know the total size upfront
•If your generator raises an exception mid-stream, the client receives a truncated response with no error status
•For static files on disk, use FileResponse instead -- it sets Content-Length and supports range requests

StreamingResponse sends data in chunks via a generator, keeping memory usage constant for any size. Pass a generator as content and set media_type for the correct Content-Type.

•Uses a generator to stream chunks -- memory stays constant regardless of data size

from fastapi import FastAPI
from fastapi.responses import StreamingResponse

app = FastAPI()

@app.get("/download")
def download():
    def generate():
        yield "id,name\n"
        for i in range(1000):
            yield f"{i},Item {i}\n"

    return StreamingResponse(generate(), media_type="text/csv")

StreamingResponse does not set Content-Length -- use FileResponse for static files

Question 8 / 18

How do you set response headers?

FastAPI provides several ways to set custom response headers:

Method 1: Response parameter

Inject a Response parameter and set headers on it. The headers are merged into the final response even when returning a dict.

Method 2: Return a Response directly

Return a JSONResponse (or other response class) with a headers dict. This gives you full control.

Method 3: Middleware

Use middleware to add headers to every response (e.g., security headers, CORS).

Common custom headers:

X-Request-ID -- trace a request across services
X-Process-Time -- time taken to process
Cache-Control -- caching behavior
X-Total-Count -- total items for paginated responses

Header naming:

HTTP headers are case-insensitive. FastAPI/Starlette normalizes them to lowercase in the response. Custom headers conventionally start with X-.

Pseudo Code

# Method 1: Response parameter (recommended)
@app.GET("/data")
function get_data(response: Response):
    response.headers["X-Custom"] = "value"
    response.headers["Cache-Control"] = "max-age=3600"
    return {"data": "value"}  # Headers are merged

# Method 2: Direct Response
@app.GET("/data")
function get_data():
    return JSONResponse(
        content={"data": "value"},
        headers={"X-Custom": "value"}
    )

Code

from fastapi import FastAPI, Response
from fastapi.responses import JSONResponse
from fastapi.testclient import TestClient
import time

app = FastAPI()

# Method 1: Response parameter (headers merged with the returned dict)
@app.get("/items/")
def list_items(response: Response):
    response.headers["X-Total-Count"] = "42"
    response.headers["Cache-Control"] = "max-age=60"
    return [{"id": 1, "name": "Widget"}]

# Method 2: Return Response directly
@app.get("/custom/")
def custom_response():
    return JSONResponse(
        content={"message": "hello"},
        headers={
            "X-Request-ID": "abc-123",
            "X-Process-Time": "0.05",
        },
    )

# Method 3: Middleware for all responses
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request

class TimingMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        start = time.perf_counter()
        response = await call_next(request)
        elapsed = time.perf_counter() - start
        response.headers["X-Process-Time"] = f"{elapsed:.4f}"
        return response

app.add_middleware(TimingMiddleware)

client = TestClient(app)

resp = client.get("/items/")
print(f"X-Total-Count: {resp.headers['x-total-count']}")
print(f"Cache-Control: {resp.headers['cache-control']}")
print(f"X-Process-Time: {resp.headers.get('x-process-time', 'set')}")

resp = client.get("/custom/")
print(f"X-Request-ID: {resp.headers['x-request-id']}")

X-Total-Count: 42
Cache-Control: max-age=60
X-Process-Time: <float value>
X-Request-ID: abc-123

Key Points

•Inject Response parameter and set .headers['X-Custom'] to add headers while still returning dicts
•Return JSONResponse directly with a headers dict for full control over the response
•Use middleware to add headers (like X-Process-Time) to every response globally
•HTTP headers are case-insensitive -- X-Custom and x-custom are the same

Gotchas

•When returning a Response directly, response_model validation is skipped entirely
•The Response parameter approach merges headers -- if you also return a Response directly, the parameter headers are ignored
•Header values must be strings -- convert numbers with str() before setting

Inject a Response parameter and set response.headers['X-Custom'] = 'value' to add headers while returning a dict. Or return JSONResponse(content=..., headers=...) for full control.

•Response parameter lets you set headers while still returning dicts/models

from fastapi import FastAPI, Response

app = FastAPI()

@app.get("/items/")
def list_items(response: Response):
    response.headers["X-Total-Count"] = "42"
    return [{"id": 1}]  # Header is merged into response

Header values must be strings -- convert numbers with str()

Question 9 / 18

How do you set and read cookies?

FastAPI provides tools for both reading cookies from requests and setting cookies in responses.

Reading cookies:

Use Cookie() to declare a cookie parameter, similar to Query() or Header(). FastAPI extracts the value from the request's Cookie header.

Setting cookies:

Use response.set_cookie() on the injected Response parameter. This adds a Set-Cookie header to the response.

Cookie parameters:

key -- cookie name
value -- cookie value
max_age -- seconds until expiry
expires -- absolute expiry datetime
path -- URL path scope (default /)
domain -- domain scope
secure -- only send over HTTPS
httponly -- not accessible via JavaScript (prevents XSS)
samesite -- CSRF protection: lax, strict, or none

Deleting cookies:

Use response.delete_cookie(key) which sets the cookie with an expired date.

Security best practices:

Always set httponly=True for session cookies
Set secure=True in production (HTTPS)
Use samesite="lax" or samesite="strict" for CSRF protection

Pseudo Code

# Reading a cookie from the request
@app.GET("/me")
function get_me(session_id: string = Cookie(default=None)):
    if session_id:
        return lookup_user(session_id)
    return {"error": "not logged in"}

# Setting a cookie in the response
@app.POST("/login")
function login(response: Response, credentials):
    token = create_session(credentials)
    response.set_cookie(
        key="session_id", value=token,
        httponly=True, secure=True, samesite="lax"
    )
    return {"message": "logged in"}

Code

from typing import Annotated
from fastapi import FastAPI, Cookie, Response
from fastapi.testclient import TestClient

app = FastAPI()

# Setting a cookie
@app.post("/login")
def login(response: Response):
    response.set_cookie(
        key="session_token",
        value="abc-123-secret",
        max_age=3600,           # 1 hour
        httponly=True,          # Not accessible via JS
        secure=False,           # True in production (HTTPS)
        samesite="lax",         # CSRF protection
    )
    return {"message": "logged in"}

# Reading a cookie
@app.get("/me")
def get_me(
    session_token: Annotated[str | None, Cookie()] = None,
):
    if session_token:
        return {"user": "alice", "session": session_token}
    return {"error": "not authenticated"}

# Deleting a cookie
@app.post("/logout")
def logout(response: Response):
    response.delete_cookie(key="session_token")
    return {"message": "logged out"}

client = TestClient(app)

# Login -- sets cookie
resp = client.post("/login")
print(f"Login: {resp.json()}")
print(f"Set-Cookie present: {'session_token' in resp.headers.get('set-cookie', '')}")

# Access with cookie
client.cookies.set("session_token", "abc-123-secret")
resp = client.get("/me")
print(f"Me: {resp.json()}")

# Without cookie
client.cookies.clear()
resp = client.get("/me")
print(f"No cookie: {resp.json()}")

Login: {'message': 'logged in'}
Set-Cookie present: True
Me: {'user': 'alice', 'session': 'abc-123-secret'}
No cookie: {'error': 'not authenticated'}

Key Points

•Read cookies with Cookie() parameter -- works like Query() but reads from the Cookie header
•Set cookies with response.set_cookie(key, value, httponly, secure, samesite)
•Delete cookies with response.delete_cookie(key) which expires the cookie
•Always set httponly=True and secure=True for session cookies in production

Gotchas

•Cookie parameter names use underscores in Python (session_token) but hyphens are also matched from the request
•secure=True means the cookie is only sent over HTTPS -- set to False during local development
•Cookies are sent with every request to the matching domain/path -- do not store large data in them

Read cookies with Cookie() as a parameter type. Set cookies with response.set_cookie(key, value, httponly=True). Delete with response.delete_cookie(key). Always use httponly=True and secure=True for session cookies.

•Cookie() reads from request; response.set_cookie() writes to response

from typing import Annotated
from fastapi import FastAPI, Cookie, Response

app = FastAPI()

@app.post("/login")
def login(response: Response):
    response.set_cookie(key="token", value="abc", httponly=True)
    return {"ok": True}

@app.get("/me")
def me(token: Annotated[str | None, Cookie()] = None):
    return {"token": token}

secure=True only sends cookies over HTTPS -- set False for local development

Question 10 / 18

How do you combine path, query, and body parameters in one endpoint?

FastAPI determines where each parameter comes from based on its type and declaration:

Parameter resolution rules:

Path parameters: If the parameter name appears in the path string "/items/{item_id}", it is a path parameter
Body parameters: If the parameter type is a Pydantic model, it is read from the request body
Query parameters: Simple types (str, int, float, bool) that are NOT in the path are query parameters
Explicit declarations: Use Path(), Query(), Body(), Header(), Cookie() to override the default behavior

Combining all three:

You can have path, query, and body parameters in the same endpoint. FastAPI resolves each one from the correct location automatically.

Priority of explicit declarations:

Path() > Query() > Body() -- but typically you only need explicit declarations when adding validation constraints or changing defaults.

Pseudo Code

# FastAPI resolution rules:
# 1. In path string -> path parameter
# 2. Pydantic model -> body parameter
# 3. Simple type not in path -> query parameter

@app.PUT("/items/{item_id}")
function update_item(
    item_id: int,              # Path (in URL)
    q: string = None,          # Query (simple type, not in path)
    item: ItemUpdate,          # Body (Pydantic model)
):
    # item_id from URL: /items/42
    # q from query string: ?q=search
    # item from JSON body: {"name": "...", "price": ...}
    return {item_id, q, item}

Code

from typing import Annotated
from fastapi import FastAPI, Path, Query
from fastapi.testclient import TestClient
from pydantic import BaseModel

app = FastAPI()

class ItemUpdate(BaseModel):
    name: str
    price: float

@app.put("/items/{item_id}")
def update_item(
    item_id: Annotated[int, Path(ge=1, description="The item ID")],
    q: Annotated[str | None, Query(max_length=50)] = None,
    item: ItemUpdate = ...,  # ... means required
):
    result = {"item_id": item_id, "item": item.model_dump()}
    if q:
        result["q"] = q
    return result

# More complex: path + query + body + header
from fastapi import Header

@app.post("/stores/{store_id}/items/")
def create_store_item(
    store_id: Annotated[int, Path(ge=1)],         # Path
    category: Annotated[str | None, Query()] = None,  # Query
    item: ItemUpdate = ...,                        # Body (Pydantic)
    x_request_id: Annotated[str | None, Header()] = None,  # Header
):
    return {
        "store_id": store_id,
        "category": category,
        "item": item.model_dump(),
        "request_id": x_request_id,
    }

client = TestClient(app)

# Path + query + body
resp = client.put(
    "/items/42?q=search",
    json={"name": "Widget", "price": 9.99},
)
print("Combined:", resp.json())

# Path + query + body + header
resp = client.post(
    "/stores/1/items/?category=electronics",
    json={"name": "Gadget", "price": 29.99},
    headers={"X-Request-ID": "req-456"},
)
print("All four:", resp.json())

Combined: {'item_id': 42, 'item': {'name': 'Widget', 'price': 9.99}, 'q': 'search'}
All four: {'store_id': 1, 'category': 'electronics', 'item': {'name': 'Gadget', 'price': 29.99}, 'request_id': 'req-456'}

Key Points

•Path params: name matches the path string; query params: simple types not in path; body: Pydantic models
•All three (plus headers and cookies) can be combined in a single endpoint
•Use Annotated[type, Path()], Annotated[type, Query()] for explicit declarations with validation
•FastAPI auto-resolves parameter sources from type hints and path string

Gotchas

•A simple type (str, int) is ALWAYS a query param unless it matches a path variable or you use Body() explicitly
•If you have two Pydantic models as parameters, FastAPI expects a JSON body with nested keys (see question 11)
•Path parameters are always required -- you cannot have optional path params

FastAPI resolves parameters automatically: names in the URL path are path params, Pydantic models are body, and simple types not in the path are query params. All three can be combined in one endpoint.

•Path: in URL; Body: Pydantic model; Query: simple types not in path

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.put("/items/{item_id}")  # path + query + body
def update(item_id: int, q: str | None = None, item: Item = ...):
    return {"id": item_id, "q": q, "item": item.model_dump()}

Simple types default to query params -- use Body() to force them into the request body

Question 11 / 18

How does FastAPI handle multiple request body parameters?

When you declare multiple Pydantic model parameters in a single endpoint, FastAPI expects a JSON body with each model as a named key.

Single body parameter:

{"name": "Widget", "price": 9.99}

The body IS the model directly.

Multiple body parameters:

{
    "item": {"name": "Widget", "price": 9.99},
    "user": {"name": "Alice"}
}

Each model becomes a key in the JSON body. The key name matches the parameter name.

Body() for singular values:

You can use Body() to embed a simple value (str, int) into the request body as a key, rather than it being treated as a query parameter.

Body(embed=True):

For a single Pydantic model, if you want the model nested under a key instead of being the root, use Body(embed=True).

Pseudo Code

# Single Pydantic param -> body IS the model
# Body: {"name": "Widget", "price": 9.99}
@app.POST("/items/")
function create(item: Item):
    pass

# Multiple Pydantic params -> each is a key
# Body: {"item": {...}, "user": {...}}
@app.POST("/items/")
function create(item: Item, user: User):
    pass

# Body(embed=True) -> single model under a key
# Body: {"item": {"name": "Widget"}}
@app.POST("/items/")
function create(item: Item = Body(embed=True)):
    pass

Code

from typing import Annotated
from fastapi import FastAPI, Body
from fastapi.testclient import TestClient
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

class User(BaseModel):
    username: str

# Multiple body params -> each becomes a JSON key
@app.post("/items-with-user/")
def create_with_user(item: Item, user: User):
    return {"item": item.model_dump(), "user": user.model_dump()}

# Singular value in body using Body()
@app.post("/items-with-note/")
def create_with_note(
    item: Item,
    importance: Annotated[int, Body(ge=1, le=5)],
):
    return {"item": item.model_dump(), "importance": importance}

# embed=True: single model under its parameter name key
@app.post("/items-embedded/")
def create_embedded(item: Annotated[Item, Body(embed=True)]):
    return item.model_dump()

client = TestClient(app)

# Multiple body params: {"item": {...}, "user": {...}}
resp = client.post("/items-with-user/", json={
    "item": {"name": "Widget", "price": 9.99},
    "user": {"username": "alice"},
})
print("Multi-body:", resp.json())

# Body value: {"item": {...}, "importance": 5}
resp = client.post("/items-with-note/", json={
    "item": {"name": "Gadget", "price": 19.99},
    "importance": 5,
})
print("With note:", resp.json())

# Embedded: {"item": {"name": "Thing", "price": 1.99}}
resp = client.post("/items-embedded/", json={
    "item": {"name": "Thing", "price": 1.99},
})
print("Embedded:", resp.json())

Multi-body: {'item': {'name': 'Widget', 'price': 9.99}, 'user': {'username': 'alice'}}
With note: {'item': {'name': 'Gadget', 'price': 19.99}, 'importance': 5}
Embedded: {'name': 'Thing', 'price': 1.99}

Key Points

•Multiple Pydantic params create a JSON body with each model as a named key
•Body() makes simple types (str, int) part of the request body instead of query params
•Body(embed=True) nests a single model under its parameter name as a key
•Parameter names become the JSON keys -- item: Item expects {"item": {...}}

Gotchas

•With a single Pydantic model, the body IS the model directly -- multiple models change the structure
•Adding a second body param changes the expected JSON shape for ALL body params -- this can break clients
•Body() with simple types requires the value in the JSON body, not the query string

With multiple Pydantic model parameters, FastAPI expects a JSON body where each model is a named key: {"item": {...}, "user": {...}}. Use Body(embed=True) to nest a single model under a key.

•Multiple Pydantic params = each becomes a key in the JSON body

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str

class User(BaseModel):
    username: str

@app.post("/create/")
def create(item: Item, user: User):
    # Body: {"item": {"name": "..."}, "user": {"username": "..."}}
    return {"item": item.model_dump(), "user": user.model_dump()}

Adding a second body param changes the expected JSON structure -- can break existing clients

Question 12 / 18

What is the Request object and when do you use it directly?

The Request object gives you direct access to the raw HTTP request. While FastAPI's parameter declarations handle most use cases, sometimes you need lower-level access.

When to use Request directly:

Accessing raw request body (non-JSON, non-form)
Reading all headers or cookies at once
Getting client IP address
Accessing the URL, method, or path
Checking content type before parsing
Forwarding requests to other services (proxying)
Working with custom content types

Key attributes:

request.method -- HTTP method (GET, POST, etc.)
request.url -- full URL
request.headers -- all headers as a mapping
request.query_params -- query string as a mapping
request.path_params -- path parameters as a dict
request.cookies -- cookies as a dict
request.client -- client IP and port
request.state -- arbitrary state for middleware/dependency data sharing

Key methods:

await request.body() -- raw body as bytes
await request.json() -- parse body as JSON
await request.form() -- parse body as form data
await request.stream() -- async iterator for streaming body

Pseudo Code

# Declare Request as a parameter -- no special annotation needed
from fastapi import Request

@app.GET("/info")
function get_info(request: Request):
    client_ip = request.client.host
    user_agent = request.headers["user-agent"]
    all_cookies = request.cookies
    full_url = str(request.url)
    return {client_ip, user_agent, full_url}

# Raw body access
@app.POST("/webhook")
async function webhook(request: Request):
    raw_body = await request.body()
    content_type = request.headers["content-type"]
    # Process raw bytes based on content type

Code

from fastapi import FastAPI, Request
from fastapi.testclient import TestClient

app = FastAPI()

# Access request metadata
@app.get("/info")
def request_info(request: Request):
    return {
        "method": request.method,
        "url": str(request.url),
        "client": request.client.host if request.client else None,
        "headers_count": len(request.headers),
        "user_agent": request.headers.get("user-agent", "unknown"),
    }

# Raw body access (useful for webhooks, custom content types)
@app.post("/webhook")
async def webhook(request: Request):
    content_type = request.headers.get("content-type", "")
    raw_body = await request.body()
    return {
        "content_type": content_type,
        "body_size": len(raw_body),
        "body_preview": raw_body[:100].decode("utf-8", errors="replace"),
    }

# Combine Request with regular params
@app.get("/items/{item_id}")
def get_item(item_id: int, request: Request):
    return {
        "item_id": item_id,
        "full_url": str(request.url),
        "query_params": dict(request.query_params),
    }

client = TestClient(app)

resp = client.get("/info")
print("Info:", resp.json()["method"], resp.json()["url"])

resp = client.post(
    "/webhook",
    content=b'{"event": "payment"}',
    headers={"Content-Type": "application/json"},
)
print("Webhook:", resp.json())

resp = client.get("/items/42?sort=price&order=asc")
print("Query params:", resp.json()["query_params"])

Info: GET http://testserver/info
Webhook: {'content_type': 'application/json', 'body_size': 20, 'body_preview': '{"event": "payment"}'}
Query params: {'sort': 'price', 'order': 'asc'}

Key Points

•Request gives direct access to method, URL, headers, cookies, client IP, and raw body
•Just declare request: Request as a parameter -- no Depends() or annotation needed
•Use await request.body() for raw bytes, await request.json() for parsed JSON
•Request can be combined with regular path/query/body parameters in the same handler

Gotchas

•request.body() and request.json() are async -- use 'await' or use sync alternatives with caution
•Reading request.body() consumes the stream -- calling it twice returns empty bytes the second time
•Request bypasses FastAPI's validation -- you handle parsing and error responses yourself

The Request object gives raw access to the HTTP request -- method, URL, headers, cookies, client IP, and body. Declare request: Request as a parameter. Use it for webhooks, proxying, or when you need data FastAPI does not expose through parameter declarations.

•Declare request: Request for raw HTTP access -- method, headers, body, client IP

from fastapi import FastAPI, Request

app = FastAPI()

@app.get("/info")
def info(request: Request):
    return {
        "method": request.method,
        "url": str(request.url),
        "client_ip": request.client.host if request.client else None,
    }

Reading request.body() consumes the stream -- it returns empty on second read

Question 13 / 18

How do you return files with FileResponse?

FileResponse sends a file from disk to the client efficiently. It uses asynchronous file reading and sets appropriate headers automatically.

What FileResponse does:

Reads the file from disk asynchronously
Sets Content-Length from the file size (enables progress bars)
Sets Content-Type from the file extension (or your media_type parameter)
Supports Content-Disposition for downloads (inline vs attachment)
Supports HTTP Range requests for partial content (video streaming, resume downloads)

Parameters:

path -- file path on disk
filename -- suggested download filename (triggers download in browser)
media_type -- override auto-detected MIME type
headers -- additional response headers
stat_result -- pre-computed os.stat result (optimization)

FileResponse vs StreamingResponse:

FileResponse: for static files on disk, sets Content-Length, supports range requests
StreamingResponse: for dynamically generated content, no Content-Length

Security:

Never pass user input directly as the file path without validation -- this leads to path traversal attacks.

Pseudo Code

# Serve a file for download
@app.GET("/download/{filename}")
function download(filename):
    file_path = safe_join(UPLOAD_DIR, filename)
    if not file_path.exists():
        raise HTTPException(404)
    return FileResponse(
        path=file_path,
        filename=filename,          # Triggers download dialog
        media_type="application/pdf" # Override content type
    )

Code

import tempfile
import os
from pathlib import Path
from fastapi import FastAPI, HTTPException
from fastapi.responses import FileResponse
from fastapi.testclient import TestClient

app = FastAPI()

# Create a temp file for demonstration
tmp_dir = tempfile.mkdtemp()
test_file = Path(tmp_dir) / "report.txt"
test_file.write_text("This is the report content.\nLine 2.\nLine 3.")

# Basic file download
@app.get("/download")
def download_report():
    return FileResponse(
        path=test_file,
        filename="report.txt",  # Triggers browser download dialog
        media_type="text/plain",
    )

# Serve file inline (display in browser, not download)
@app.get("/view")
def view_report():
    return FileResponse(
        path=test_file,
        media_type="text/plain",
        # No filename = browser displays inline
    )

# Dynamic file serving with path validation
UPLOAD_DIR = Path(tmp_dir)

@app.get("/files/{filename}")
def get_file(filename: str):
    # SECURITY: validate filename to prevent path traversal
    safe_path = UPLOAD_DIR / Path(filename).name  # .name strips directory components
    if not safe_path.exists():
        raise HTTPException(status_code=404, detail="File not found")
    return FileResponse(path=safe_path)

client = TestClient(app)

resp = client.get("/download")
print(f"Status: {resp.status_code}")
print(f"Content-Disposition: {resp.headers.get('content-disposition')}")
print(f"Content-Length: {resp.headers.get('content-length')}")
print(f"Content: {resp.text[:30]}")

# Cleanup
os.unlink(test_file)
os.rmdir(tmp_dir)

Status: 200
Content-Disposition: attachment; filename="report.txt"
Content-Length: 45
Content: This is the report content.

Key Points

•FileResponse sends files from disk with automatic Content-Length and Content-Type headers
•Set filename parameter to trigger browser download dialog (Content-Disposition: attachment)
•Without filename, the file is displayed inline in the browser
•FileResponse supports range requests for video streaming and resumable downloads

Gotchas

•NEVER pass raw user input as the file path -- always validate to prevent path traversal (../../etc/passwd)
•FileResponse raises an error if the file does not exist -- check before returning
•For dynamically generated content, use StreamingResponse instead -- FileResponse requires a file on disk

FileResponse serves a file from disk with auto-detected Content-Type and Content-Length. Set filename to trigger browser download. It supports range requests for video streaming and resumable downloads.

•FileResponse sets Content-Length and supports range requests -- use for files on disk

from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

@app.get("/download")
def download():
    return FileResponse(
        path="/path/to/report.pdf",
        filename="report.pdf",  # triggers download
        media_type="application/pdf",
    )

Never pass user input directly as file path -- validate to prevent path traversal attacks

Question 14 / 18

How do you handle optional request body fields?

Optional fields in Pydantic models can be declared in several ways, each with different behavior:

Method 1: Default value

Give a field a default value. It becomes optional in the request body.

tags: list[str] = []

Method 2: None type with default None

Use | None (or Optional[...]) with = None. The field is optional and defaults to None.

description: str | None = None

Method 3: All-optional model for PATCH updates

For partial updates, make ALL fields optional so clients send only what changed.

Key distinction: missing vs None

A field with = None that is not sent in the body -> value is None
A field that IS sent as null -> value is also None
To distinguish "not sent" from "sent as null", use model.model_fields_set

PATCH partial updates:

For PATCH endpoints, create a model where all fields are optional, then use model_dump(exclude_unset=True) to get only the fields the client actually sent.

Pseudo Code

# Required vs optional fields
class ItemCreate:
    name: str              # Required -- must be in the body
    price: float           # Required
    description: str | None = None  # Optional, defaults to None
    tags: list[str] = []   # Optional, defaults to empty list

# PATCH partial update model
class ItemUpdate:
    name: str | None = None    # All fields optional
    price: float | None = None

@app.PATCH("/items/{id}")
function patch_item(id, updates: ItemUpdate):
    # Only get fields the client sent
    changes = updates.model_dump(exclude_unset=True)
    # {"price": 19.99} if client only sent price
    apply_changes(id, changes)

Code

from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel

app = FastAPI()

# Mix of required and optional fields
class ItemCreate(BaseModel):
    name: str                       # Required
    price: float                    # Required
    description: str | None = None  # Optional, defaults to None
    tags: list[str] = []            # Optional, defaults to empty list
    discount: float = 0.0           # Optional, defaults to 0.0

@app.post("/items/")
def create_item(item: ItemCreate):
    return item.model_dump()

# All-optional model for PATCH
class ItemUpdate(BaseModel):
    name: str | None = None
    price: float | None = None
    description: str | None = None
    tags: list[str] | None = None

@app.patch("/items/{item_id}")
def patch_item(item_id: int, updates: ItemUpdate):
    # exclude_unset=True: only fields the client actually sent
    changes = updates.model_dump(exclude_unset=True)
    return {"item_id": item_id, "changes": changes}

client = TestClient(app)

# Only required fields -- optional ones get defaults
resp = client.post("/items/", json={"name": "Widget", "price": 9.99})
print("Minimal:", resp.json())

# PATCH: send only what changed
resp = client.patch("/items/1", json={"price": 19.99})
print("Patch:", resp.json())

# PATCH: send null explicitly
resp = client.patch("/items/1", json={"description": None})
print("Null:", resp.json())

Minimal: {'name': 'Widget', 'price': 9.99, 'description': None, 'tags': [], 'discount': 0.0}
Patch: {'item_id': 1, 'changes': {'price': 19.99}}
Null: {'item_id': 1, 'changes': {'description': None}}

Key Points

•Fields with default values (= None, = [], = 0) are optional in the request body
•str | None = None means the field can be a string, null, or omitted entirely
•model_dump(exclude_unset=True) returns only fields the client sent -- essential for PATCH updates
•model_fields_set tells you exactly which fields were provided in the request

Gotchas

•str | None without = None is still REQUIRED -- the client must send it (even as null)
•model_dump(exclude_unset=True) distinguishes 'not sent' from 'sent as None' -- model_dump() alone does not
•An empty dict {} is a valid body for an all-optional model -- it passes validation

Use field: str | None = None for optional fields that default to None. For PATCH updates, make all fields optional and use model_dump(exclude_unset=True) to get only what the client sent.

•model_dump(exclude_unset=True) returns only client-provided fields for partial updates

from pydantic import BaseModel
from fastapi import FastAPI

app = FastAPI()

class ItemUpdate(BaseModel):
    name: str | None = None
    price: float | None = None

@app.patch("/items/{id}")
def patch(id: int, updates: ItemUpdate):
    changes = updates.model_dump(exclude_unset=True)
    return {"id": id, "changes": changes}  # Only sent fields

str | None without = None is still required -- the default value makes it optional

Question 15 / 18

What is response_model_exclude and response_model_include?

FastAPI's route decorators accept response_model_include and response_model_exclude parameters to fine-tune which fields appear in the response without creating a separate response model.

response_model_include:

A set of field names to include. Only these fields appear in the response.

response_model_exclude:

A set of field names to exclude. All fields EXCEPT these appear in the response.

When to use:

Quick prototyping when creating a separate response model feels heavy
Excluding one or two sensitive fields from an existing model
Including only specific fields for a summary endpoint

When NOT to use:

Production APIs -- prefer separate Pydantic response models instead
When you need different validation rules for input vs output
When the exclusion logic is complex or involves nested fields

Other response_model options:

response_model_exclude_unset=True -- omit fields that were not explicitly set
response_model_exclude_defaults=True -- omit fields that equal their default value
response_model_exclude_none=True -- omit fields with None values

Pseudo Code

class User:
    id, name, email, password, is_admin

# Include only specific fields
@app.GET("/summary", response_model=User, response_model_include={"id", "name"})
# Response: {"id": 1, "name": "Alice"}

# Exclude sensitive fields
@app.GET("/profile", response_model=User, response_model_exclude={"password", "is_admin"})
# Response: {"id": 1, "name": "Alice", "email": "alice@example.com"}

# Exclude unset/none values
@app.GET("/compact", response_model=User, response_model_exclude_none=True)
# Omits any field that is None

Code

from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int
    name: str
    email: str
    hashed_password: str
    is_admin: bool
    bio: str | None = None

fake_user = User(
    id=1, name="Alice", email="alice@example.com",
    hashed_password="$2b$12$hash", is_admin=True, bio=None,
)

# Include only specific fields
@app.get("/users/summary", response_model=User,
         response_model_include={"id", "name"})
def user_summary():
    return fake_user

# Exclude sensitive fields
@app.get("/users/profile", response_model=User,
         response_model_exclude={"hashed_password", "is_admin"})
def user_profile():
    return fake_user

# Exclude None values
@app.get("/users/compact", response_model=User,
         response_model_exclude={"hashed_password", "is_admin"},
         response_model_exclude_none=True)
def user_compact():
    return fake_user

client = TestClient(app)

print("Summary:", client.get("/users/summary").json())
print("Profile:", client.get("/users/profile").json())
print("Compact:", client.get("/users/compact").json())

Summary: {'id': 1, 'name': 'Alice'}
Profile: {'id': 1, 'name': 'Alice', 'email': 'alice@example.com', 'bio': None}
Compact: {'id': 1, 'name': 'Alice', 'email': 'alice@example.com'}

Key Points

•response_model_include limits output to only the specified field names
•response_model_exclude removes specified fields from the output
•response_model_exclude_none=True omits fields with None values for cleaner responses
•These are shortcuts -- prefer separate response Pydantic models for production APIs

Gotchas

•Include/exclude are quick hacks -- they do not generate correct OpenAPI schemas for the filtered model
•Nested model fields require dict syntax for include/exclude: {"address": {"city"}}
•Using both include and exclude together: include is applied first, then exclude removes from that set

response_model_include limits output to specified fields. response_model_exclude removes specified fields. They are shortcuts for filtering without creating separate response models. Prefer dedicated response models for production.

•include/exclude filter fields without creating a separate response model

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    id: int
    name: str
    password: str

@app.get("/user", response_model=User,
         response_model_exclude={"password"})
def get_user():
    return User(id=1, name="Alice", password="secret")
# Returns: {"id": 1, "name": "Alice"}

Include/exclude do not update the OpenAPI schema -- prefer separate response models for production

Question 16 / 18

How do you handle multiple file uploads?

FastAPI handles multiple file uploads by declaring the parameter as list[UploadFile]. The client sends multiple files under the same form field name.

Two approaches:

1. Multiple files, same field name

Declare files: list[UploadFile]. The client sends multiple files under the files field in a multipart form.

2. Multiple files, different field names

Declare separate UploadFile parameters with different names for files that serve different purposes (e.g., photo and document).

Combining with form data:

You can combine multiple file uploads with regular form fields. All are sent as multipart/form-data.

Processing tips:

Iterate over the list to process each file
Check file.content_type and file.size for validation
Use await file.read() for each file's contents
Close files after processing with await file.close()

Pseudo Code

# Multiple files, same field
@app.POST("/upload-many/")
function upload(files: list[UploadFile]):
    results = []
    for file in files:
        content = await file.read()
        results.append({name: file.filename, size: len(content)})
    return results

# Multiple files, different fields
@app.POST("/upload-docs/")
function upload(photo: UploadFile, resume: UploadFile):
    return {photo: photo.filename, resume: resume.filename}

Code

from typing import Annotated
from fastapi import FastAPI, File, UploadFile
from fastapi.testclient import TestClient

app = FastAPI()

# Multiple files under the same field name
@app.post("/upload-many/")
async def upload_many(files: list[UploadFile]):
    results = []
    for file in files:
        contents = await file.read()
        results.append({
            "filename": file.filename,
            "size": len(contents),
            "content_type": file.content_type,
        })
    return {"file_count": len(results), "files": results}

# Different files for different purposes
@app.post("/apply/")
async def apply_job(
    resume: UploadFile,
    cover_letter: UploadFile,
    portfolio: UploadFile | None = None,  # Optional file
):
    result = {
        "resume": resume.filename,
        "cover_letter": cover_letter.filename,
    }
    if portfolio:
        result["portfolio"] = portfolio.filename
    return result

client = TestClient(app)

# Upload multiple files
response = client.post("/upload-many/", files=[
    ("files", ("doc1.txt", b"Content of doc 1", "text/plain")),
    ("files", ("doc2.txt", b"Content of doc 2", "text/plain")),
    ("files", ("image.png", b"PNG data", "image/png")),
])
print("Count:", response.json()["file_count"])
for f in response.json()["files"]:
    print(f"  {f['filename']}: {f['size']} bytes")

# Upload to separate fields
response = client.post("/apply/", files={
    "resume": ("resume.pdf", b"PDF data", "application/pdf"),
    "cover_letter": ("letter.txt", b"Dear Sir", "text/plain"),
})
print("Apply:", response.json())

Count: 3
doc1.txt: 16 bytes
doc2.txt: 16 bytes
image.png: 8 bytes
Apply: {'resume': 'resume.pdf', 'cover_letter': 'letter.txt'}

Key Points

•list[UploadFile] accepts multiple files under the same form field name
•Separate UploadFile parameters accept files under different field names
•Optional files use UploadFile | None = None with a default of None
•All files are sent as multipart/form-data and processed with await file.read()

Gotchas

•All files are loaded into memory when using await file.read() -- process large files in chunks instead
•The form field name must match: list[UploadFile] needs all files under the same key (e.g., 'files')
•There is no built-in limit on file count or total size -- add validation to prevent abuse

Use list[UploadFile] for multiple files under the same field, or separate UploadFile parameters for different file purposes. All are sent as multipart/form-data.

•list[UploadFile] accepts multiple files from a single form field

from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/upload/")
async def upload(files: list[UploadFile]):
    return [
        {"name": f.filename, "size": len(await f.read())}
        for f in files
    ]

No built-in size or count limits -- validate manually to prevent abuse

Question 17 / 18

How do you accept both JSON and Form data in the same endpoint?

FastAPI does not natively support accepting both JSON and Form data in a single endpoint. Each endpoint handler declares a specific content type expectation (JSON via Pydantic models, form via Form()). You cannot mix Body() and Form() in the same function.

Workarounds:

1. Use the raw Request object

Read the raw request, check the Content-Type header, and parse accordingly.

2. Separate endpoints

Create two endpoints (one for JSON, one for form data) that call the same logic.

3. Content-Type middleware

Use middleware to convert form data to JSON before it reaches the handler.

Why this limitation exists:

JSON (application/json) and form data (application/x-www-form-urlencoded or multipart/form-data) are fundamentally different encodings. OpenAPI spec defines a single content type per request body schema, and FastAPI follows this strictly.

Pseudo Code

# Approach 1: Raw Request with content-type detection
@app.POST("/items/")
async function create_item(request: Request):
    content_type = request.headers["content-type"]
    if "application/json" in content_type:
        data = await request.json()
    elif "form" in content_type:
        form = await request.form()
        data = dict(form)
    else:
        raise 415 Unsupported Media Type
    
    # Validate with Pydantic manually
    item = ItemCreate.model_validate(data)
    return item

# Approach 2: Separate endpoints, shared logic
@app.POST("/items/json")
def create_json(item: ItemCreate):
    return save_item(item)

@app.POST("/items/form")
def create_form(name: str = Form(), price: float = Form()):
    item = ItemCreate(name=name, price=price)
    return save_item(item)

Code

from fastapi import FastAPI, Form, Request, HTTPException
from fastapi.testclient import TestClient
from pydantic import BaseModel, ValidationError

app = FastAPI()

class ItemCreate(BaseModel):
    name: str
    price: float

# Approach 1: Content-Type detection with raw Request
@app.post("/items/")
async def create_item(request: Request):
    content_type = request.headers.get("content-type", "")

    if "application/json" in content_type:
        data = await request.json()
    elif "form" in content_type:
        form = await request.form()
        data = dict(form)
    else:
        raise HTTPException(status_code=415, detail="Unsupported content type")

    # Validate manually with Pydantic
    try:
        item = ItemCreate.model_validate(data)
    except ValidationError as e:
        raise HTTPException(status_code=422, detail=e.errors())

    return {"item": item.model_dump(), "source": content_type}

# Approach 2: Separate endpoints with shared logic
def save_item(item: ItemCreate):
    return {"saved": item.model_dump()}

@app.post("/items/json")
def create_json(item: ItemCreate):
    return save_item(item)

@app.post("/items/form")
def create_form(
    name: str = Form(),
    price: float = Form(),
):
    return save_item(ItemCreate(name=name, price=price))

client = TestClient(app)

# JSON request
resp = client.post("/items/", json={"name": "Widget", "price": 9.99})
print("JSON:", resp.json()["item"])

# Form request
resp = client.post("/items/", data={"name": "Gadget", "price": "19.99"})
print("Form:", resp.json()["item"])

# Separate endpoints
print("JSON endpoint:", client.post("/items/json", json={"name": "A", "price": 1.0}).json())
print("Form endpoint:", client.post("/items/form", data={"name": "B", "price": "2.0"}).json())

JSON: {'name': 'Widget', 'price': 9.99}
Form: {'name': 'Gadget', 'price': 19.99}
JSON endpoint: {'saved': {'name': 'A', 'price': 1.0}}
Form endpoint: {'saved': {'name': 'B', 'price': 2.0}}

Key Points

•FastAPI does not natively support both JSON and form data in one endpoint
•Use the raw Request object with Content-Type detection to handle both formats
•Validate manually with Pydantic model_validate() when using the Request approach
•Alternative: create separate endpoints for JSON and form that share business logic

Gotchas

•The Request approach bypasses FastAPI's auto-validation and auto-documentation
•Form data sends all values as strings -- Pydantic coerces '9.99' to float, but complex nested objects are not supported
•The OpenAPI schema cannot represent an endpoint that accepts both JSON and form data

FastAPI does not natively support both JSON and form data in one endpoint. Use the raw Request object with Content-Type detection, or create separate endpoints that share business logic.

•Check Content-Type header and parse accordingly using raw Request

from fastapi import FastAPI, Request, HTTPException
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")
async def create(request: Request):
    ct = request.headers.get("content-type", "")
    if "json" in ct:
        data = await request.json()
    elif "form" in ct:
        data = dict(await request.form())
    else:
        raise HTTPException(415, "Unsupported type")
    return Item.model_validate(data).model_dump()

Using Request bypasses auto-validation and OpenAPI docs -- validate manually with Pydantic

Question 18 / 18

How does FastAPI handle request body with nested models?

Pydantic models can contain other Pydantic models as fields, creating nested structures. FastAPI validates the entire nested hierarchy automatically.

How nested validation works:

The outer model's fields are validated first
For each field that is a Pydantic model, its fields are validated recursively
If any nested field fails validation, the error path includes the full location (e.g., body -> address -> zip_code)
The OpenAPI schema includes the full nested structure in Swagger docs

Common patterns:

Address inside User: address: Address
List of nested items: items: list[OrderItem]
Optional nested object: metadata: Metadata | None = None
Deeply nested: models inside models inside models

JSON Schema:

Nested Pydantic models generate nested JSON Schema objects in the OpenAPI docs, with each model appearing in the components/schemas section and referenced via $ref.

Performance:

Pydantic v2's Rust core validates nested models efficiently. Deep nesting does not significantly impact performance.

Pseudo Code

# Define nested models
class Address:
    street: str
    city: str
    zip_code: str

class OrderItem:
    product: str
    quantity: int
    price: float

class Order:
    customer_name: str
    shipping_address: Address           # Nested model
    items: list[OrderItem]              # List of nested models
    billing_address: Address | None = None  # Optional nested

# JSON body:
# {
#   "customer_name": "Alice",
#   "shipping_address": {"street": "...", "city": "...", "zip_code": "..."},
#   "items": [{"product": "...", "quantity": 1, "price": 9.99}]
# }

Code

from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI()

class Address(BaseModel):
    street: str
    city: str
    state: str = Field(min_length=2, max_length=2)
    zip_code: str

class OrderItem(BaseModel):
    product_name: str
    quantity: int = Field(ge=1)
    unit_price: float = Field(gt=0)

class OrderCreate(BaseModel):
    customer_name: str
    shipping_address: Address                      # Required nested
    items: list[OrderItem] = Field(min_length=1)   # List of nested
    billing_address: Address | None = None         # Optional nested
    notes: str | None = None

@app.post("/orders/", status_code=201)
def create_order(order: OrderCreate):
    total = sum(i.quantity * i.unit_price for i in order.items)
    return {
        "customer": order.customer_name,
        "shipping_city": order.shipping_address.city,
        "item_count": len(order.items),
        "total": round(total, 2),
    }

client = TestClient(app)

# Valid nested request
resp = client.post("/orders/", json={
    "customer_name": "Alice",
    "shipping_address": {
        "street": "123 Main St",
        "city": "Springfield",
        "state": "IL",
        "zip_code": "62701",
    },
    "items": [
        {"product_name": "Widget", "quantity": 2, "unit_price": 9.99},
        {"product_name": "Gadget", "quantity": 1, "unit_price": 24.99},
    ],
})
print("Order:", resp.json())

# Invalid nested field
resp = client.post("/orders/", json={
    "customer_name": "Bob",
    "shipping_address": {
        "street": "456 Oak Ave",
        "city": "Dallas",
        "state": "Texas",  # Too long -- must be 2 chars
        "zip_code": "75201",
    },
    "items": [{"product_name": "X", "quantity": 1, "unit_price": 5.0}],
})
print("Invalid nested:", resp.status_code)

Order: {'customer': 'Alice', 'shipping_city': 'Springfield', 'item_count': 2, 'total': 44.97}
Invalid nested: 422

Key Points

•Pydantic models can contain other models as fields for deeply nested validation
•list[Model] validates each item in the list against the nested model schema
•Optional nested models use Model | None = None for optional sub-objects
•Validation errors include the full path (e.g., body -> shipping_address -> state)

Gotchas

•Deeply nested models increase the JSON Schema complexity in Swagger docs -- keep nesting reasonable
•Circular references (Model A contains Model B which contains Model A) require model_rebuild() to work
•Nested model changes affect all endpoints using the parent model -- extract shared models carefully

Pydantic models can contain other Pydantic models as fields, creating validated nested JSON structures. Use list[Model] for arrays of nested objects and Model | None = None for optional nesting. Validation errors show the full path to the invalid field.

•Nested Pydantic models are validated recursively with full error path reporting

from pydantic import BaseModel
from fastapi import FastAPI

app = FastAPI()

class Address(BaseModel):
    city: str
    zip_code: str

class User(BaseModel):
    name: str
    address: Address  # Nested model

@app.post("/users/")
def create(user: User):
    return {"name": user.name, "city": user.address.city}
# Body: {"name": "Alice", "address": {"city": "NYC", "zip_code": "10001"}}

Circular model references require Pydantic's model_rebuild() to resolve forward references

Built by onllm.dev

Home GitHub Support awesomePrep

How do you accept JSON request bodies using Pydantic models?

How it works:

Key features:

Validation errors:

How do you handle Form data in FastAPI?

How it works:

Why Form is separate from Body:

Common use cases:

Annotated syntax (recommended):

How do you handle file uploads with File and UploadFile?

1. bytes with File()

2. UploadFile

UploadFile attributes:

UploadFile async methods:

Content type:

Annotated syntax:

What is response_model and how does it filter response data?

What response_model does:

Why it matters:

How filtering works:

Return type annotation vs response_model:

How do you set HTTP status codes in responses?

1. Decorator parameter (default status code)

2. status module constants

3. Response parameter (dynamic status code)

4. Raise HTTPException

5. Return a Response directly

Common status codes:

What is the difference between JSONResponse, HTMLResponse, and PlainTextResponse?

JSONResponse (default)

HTMLResponse

PlainTextResponse

How to use them:

Other useful response classes:

How do you use StreamingResponse for large data?

How it works:

When to use StreamingResponse:

Parameters:

For file downloads:

How do you set response headers?

Method 1: Response parameter

Method 2: Return a Response directly

Method 3: Middleware

Common custom headers:

Header naming:

How do you set and read cookies?

Reading cookies:

Setting cookies:

Cookie parameters:

Deleting cookies:

Security best practices:

How do you combine path, query, and body parameters in one endpoint?

Parameter resolution rules:

Combining all three:

Priority of explicit declarations:

How does FastAPI handle multiple request body parameters?

Single body parameter:

Multiple body parameters:

Body() for singular values:

Body(embed=True):

What is the Request object and when do you use it directly?

When to use Request directly:

Key attributes:

Key methods:

How do you return files with FileResponse?

What FileResponse does:

Parameters:

FileResponse vs StreamingResponse:

Security:

How do you handle optional request body fields?

Method 1: Default value

Method 2: None type with default None

Method 3: All-optional model for PATCH updates

Key distinction: missing vs None

PATCH partial updates:

What is response_model_exclude and response_model_include?

response_model_include:

response_model_exclude:

When to use:

When NOT to use:

1. `bytes` with `File()`

2. `UploadFile`

2. `status` module constants

3. `Response` parameter (dynamic status code)

4. Raise `HTTPException`

5. Return a `Response` directly