Optional query parameters in FastAPI - Step-by-Step Execution

Concept Flow - Optional query parameters

Request received

↓

Check query parameters

↓

Is optional param present?

No→Use default or None

|Yes↓

Use provided param value

↓

Process request with param

↓

Send response

When a request comes in, FastAPI checks if the optional query parameter is given. If yes, it uses it; if not, it uses a default or None.

Execution Sample

FastAPI

from fastapi import FastAPI
from typing import Optional

app = FastAPI()

@app.get("/items/")
def read_items(q: Optional[str] = None):
    return {"q": q}

This code defines an endpoint with an optional query parameter 'q'. If 'q' is not provided, it defaults to None.

Execution Table

Step	Request URL	Query Param 'q'	Parameter Value Used	Response
1	/items/	None	None	{"q": null}
2	/items/?q=apple	apple	apple	{"q": "apple"}
3	/items/?q=	empty string	empty string	{"q": ""}
4	/items/?other=123	None	None	{"q": null}
5	Request ends	-	-	-

💡 Request processing ends after sending response with parameter value or None if missing.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	Final
q	None	None	"apple"	""	None	Varies per request

Key Moments - 2 Insights

Why does 'q' become None when the query parameter is missing?

Because the function defines 'q' as Optional[str] with default None, FastAPI assigns None when 'q' is not in the URL (see execution_table step 1 and 4).

What happens if the query parameter 'q' is present but empty like '?q='?

FastAPI treats it as an empty string, not None (see execution_table step 3). So 'q' is '' (empty string), which is different from None.

Visual Quiz - 3 Questions

Look at the execution table, what is the value of 'q' at step 2?

A None

B "" (empty string)

C "apple"

D 123

💡 Hint

Check the 'Parameter Value Used' column at step 2 in the execution_table.

At which step does 'q' have an empty string value?

A Step 1

B Step 3

C Step 2

D Step 4

💡 Hint

Look for 'empty string' in the 'Query Param q' column in the execution_table.

If you remove 'Optional' and set 'q: str = None', what will happen when 'q' is missing?

A FastAPI will raise an error for missing required parameter

B FastAPI will accept None as valid

C FastAPI will treat 'q' as empty string

D FastAPI will ignore 'q' and proceed

💡 Hint

Refer to how FastAPI treats required vs optional parameters in the variable_tracker and key_moments.

Concept Snapshot

Optional query parameters in FastAPI:
- Use typing.Optional[type] with default None
- If param missing, value is None
- If param present but empty, value is empty string
- Allows flexible API calls without errors
- Example: def read_items(q: Optional[str] = None)

Full Transcript

This example shows how FastAPI handles optional query parameters. When a request comes in, FastAPI checks if the query parameter 'q' is present. If it is, FastAPI uses its value. If not, it uses None because 'q' is defined as Optional[str] with default None. If the parameter is present but empty, FastAPI treats it as an empty string. This behavior allows APIs to accept flexible inputs without errors. The execution table traces requests with different URLs and shows how 'q' changes. The variable tracker follows 'q' across steps. Key moments clarify why None is used when missing and how empty strings differ. The quiz tests understanding of these behaviors.