Custom response classes in FastAPI - Step-by-Step Execution

Concept Flow - Custom response classes

Define Custom Response Class

↓

Use Custom Response in Path Operation

↓

Request Received

↓

Path Operation Executes

↓

Custom Response Class Formats Data

↓

Send Formatted Response to Client

This flow shows how you define a custom response class, use it in a route, and how FastAPI sends the formatted response to the client.

Execution Sample

FastAPI

from fastapi import FastAPI, Response

app = FastAPI()

class PlainTextResponse(Response):
    media_type = "text/plain"

@app.get("/hello", response_class=PlainTextResponse)
async def hello():
    return "Hello, friend!"

This code defines a custom plain text response class and uses it in a FastAPI route to return plain text instead of JSON.

Execution Table

Step	Action	Input/State	Output/State
1	Define PlainTextResponse class	None	Class with media_type='text/plain' created
2	Define /hello route with response_class=PlainTextResponse	None	Route ready to return plain text
3	Client sends GET request to /hello	Request received	Path operation triggered
4	Execute hello() function	No input params	Returns string 'Hello, friend!'
5	FastAPI uses PlainTextResponse to format response	String 'Hello, friend!'	Response body set to 'Hello, friend!' with Content-Type 'text/plain'
6	Send response to client	Formatted response	Client receives plain text 'Hello, friend!'
7	End	Response sent	Request cycle complete

💡 Request cycle ends after sending the formatted plain text response to the client

Variable Tracker

Variable	Start	After Step 4	After Step 5	Final
response_class	None	PlainTextResponse	PlainTextResponse	PlainTextResponse
return_value	None	"Hello, friend!"	"Hello, friend!"	"Hello, friend!"
response_body	None	None	"Hello, friend!"	"Hello, friend!"
content_type	None	None	"text/plain"	"text/plain"

Key Moments - 2 Insights

Why does the response have Content-Type 'text/plain' instead of 'application/json'?

Because the custom response class PlainTextResponse sets media_type to 'text/plain', FastAPI uses it to set the Content-Type header as shown in execution_table step 5.

What happens if you don't specify response_class in the route decorator?

FastAPI defaults to JSONResponse, so the output would be JSON formatted, not plain text. This is implied by the difference in step 2 where response_class is set.

Visual Quiz - 3 Questions

Look at the execution table, what is the response_body after step 5?

A "Hello, friend!"

B None

C An empty string

D A JSON object

💡 Hint

Check the 'response_body' variable in variable_tracker after step 5

At which step does FastAPI set the Content-Type header to 'text/plain'?

A Step 3

B Step 4

C Step 5

D Step 6

💡 Hint

Look at the 'Action' and 'Output/State' columns in execution_table step 5

If you remove the response_class=PlainTextResponse from the route, what changes in the response?

A Response will be HTML

B Response will be JSON with Content-Type 'application/json'

C Response will be plain text anyway

D Response will cause an error

💡 Hint

Refer to key_moments about default response_class behavior

Concept Snapshot

Custom response classes in FastAPI let you control how data is sent back.
Define a class inheriting Response and set media_type.
Use response_class parameter in route decorator.
FastAPI uses it to format and set Content-Type.
Useful for plain text, HTML, or other formats.

Full Transcript

This visual execution shows how FastAPI handles custom response classes. First, you define a class inheriting from Response and set the media_type to the desired content type, like 'text/plain'. Then, you use this class in a route with the response_class parameter. When a client requests that route, FastAPI runs the function, gets the return value, and uses the custom response class to format the output and set the Content-Type header accordingly. The response is then sent back to the client as plain text instead of JSON. This process helps you control exactly how your API sends data.

Practice

1. What is the main purpose of using Custom response classes in FastAPI?

easy

A. To handle user authentication

B. To create database models automatically

C. To control how FastAPI sends data back to the client

D. To manage background tasks

Solution

1. Step 1: Understand the role of response classes

   Response classes in FastAPI define how data is formatted and sent back to the client, such as JSON, HTML, or plain text.

2. Step 2: Identify the correct purpose

   Custom response classes let you control the exact format and headers of the response, improving clarity and compatibility.

3. Final Answer:

   To control how FastAPI sends data back to the client -> Option C

4. Quick Check:

   Custom response classes = control response format [OK]

Hint: Response classes define output format in FastAPI [OK]

Common Mistakes:

• Confusing response classes with database models
• Thinking they handle authentication
• Assuming they manage background tasks

2. Which of the following is the correct way to use a custom response class to return plain text in FastAPI?

easy

A. return PlainTextResponse(content="Hello World")

B. return JSONResponse(content="Hello World")

C. return HTMLResponse(content=123)

D. return FileResponse(path="hello.txt")

Solution

1. Step 1: Identify the correct response class for plain text

   FastAPI provides PlainTextResponse to send plain text content.

2. Step 2: Check the usage syntax

   The correct syntax is to pass the text string as the content argument.

3. Final Answer:

   return PlainTextResponse(content="Hello World") -> Option A

4. Quick Check:

   PlainTextResponse with content string = return PlainTextResponse(content="Hello World") [OK]

Hint: Use PlainTextResponse for text content [OK]

Common Mistakes:

• Using JSONResponse for plain text
• Passing non-string content to HTMLResponse
• Using FileResponse for text content

3. Given the code below, what will be the response content type sent to the client?

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()

@app.get("/", response_class=HTMLResponse)
async def read_root():
    return "
Welcome
"

medium

A. text/html

B. application/json

C. text/plain

D. application/octet-stream

Solution

1. Step 1: Identify the response class used

   The route uses response_class=HTMLResponse, which sets the content type to HTML.

2. Step 2: Understand the content type sent

   HTMLResponse sends content with the header Content-Type: text/html.

3. Final Answer:

   text/html -> Option A

4. Quick Check:

   HTMLResponse = text/html content type [OK]

Hint: HTMLResponse sets content type to text/html [OK]

Common Mistakes:

• Assuming JSON is default content type
• Confusing plain text with HTML content type
• Ignoring the response_class parameter

4. What is wrong with this FastAPI endpoint using a custom response class?

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/data")
async def get_data():
    return JSONResponse(content=[1, 2, 3], status_code="200")

medium

A. Missing return type annotation

B. content must be a dictionary, not a list

C. JSONResponse cannot be used in async functions

D. status_code should be an integer, not a string

Solution

1. Step 1: Check the status_code argument type

   Status codes must be integers, but here it is passed as a string "200".

2. Step 2: Understand the impact of wrong type

   Passing a string causes a runtime error or unexpected behavior in FastAPI.

3. Final Answer:

   status_code should be an integer, not a string -> Option D

4. Quick Check:

   Status code must be int, not str [OK]

Hint: Use integer for status_code, not string [OK]

Common Mistakes:

• Passing status_code as string
• Thinking content must be dict only
• Believing JSONResponse can't be async

5. You want to create a FastAPI endpoint that returns a CSV file for download using a custom response class. Which approach correctly sets the response to send a CSV file named "report.csv" with content "name,age\nAlice,30"?

hard

A. Use JSONResponse with content as CSV string and set media_type to 'text/csv'

B. Use StreamingResponse with content as bytes and set headers for CSV download

C. Use PlainTextResponse with content as CSV string and no headers

D. Use HTMLResponse with CSV content inside <pre> tags

Solution

1. Step 1: Choose the correct response class for file download

   StreamingResponse is suitable for sending files or streams with custom headers.

2. Step 2: Set content and headers properly

   Content should be bytes, and headers must include Content-Disposition to prompt file download with the filename.

3. Final Answer:

   Use StreamingResponse with content as bytes and set headers for CSV download -> Option B

4. Quick Check:

   StreamingResponse + headers = file download [OK]

Hint: Use StreamingResponse with headers for file downloads [OK]

Common Mistakes:

• Using JSONResponse for CSV files
• Not setting Content-Disposition header
• Using HTMLResponse for file content