Basic query parameter declaration in FastAPI - Step-by-Step Execution

Concept Flow - Basic query parameter declaration

Start HTTP GET Request

↓

Check URL for query parameters

↓

Match query parameters to function args

↓

Assign default if missing

↓

Execute function with parameters

↓

Return response with parameter values

This flow shows how FastAPI reads query parameters from the URL, matches them to function arguments, assigns defaults if needed, and returns the response.

Execution Sample

FastAPI

from fastapi import FastAPI
app = FastAPI()

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

This code defines a GET endpoint that reads an optional query parameter 'q' and returns it in the response.

Execution Table

Step	Request URL	Query Parameter 'q'	Parameter Value in Function	Response
1	GET /items/	None	None (default)	{"q": null}
2	GET /items/?q=apple	apple	"apple"	{"q": "apple"}
3	GET /items/?q=123	123	"123"	{"q": "123"}
4	GET /items/?q=	Empty string	""	{"q": ""}
5	GET /items/?other=xyz	No 'q' param	None (default)	{"q": null}

💡 Execution stops after sending the response for each request.

Variable Tracker

Variable	Start	Request 1	Request 2	Request 3	Request 4	Request 5
q	None	None	"apple"	"123"	""	None

Key Moments - 3 Insights

Why is 'q' None when the URL has no query parameter?

Because the function argument 'q' has a default value of None, so if the query parameter is missing, FastAPI assigns None (see execution_table row 1 and 5).

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

FastAPI passes an empty string "" to the function argument 'q' (see execution_table row 4), not None.

Does FastAPI automatically convert query parameters to types?

Yes, but here 'q' is a string, so values like '123' remain strings (see execution_table row 3).

Visual Quiz - 3 Questions

Look at the execution table, what is the value of 'q' in the function when the request URL is '/items/?q=apple'?

A "apple"

B None

C ""

D 123

💡 Hint

Check execution_table row 2 under 'Parameter Value in Function'

At which request does the query parameter 'q' get the value None?

A Request 2

B Request 1

C Request 3

D Request 4

💡 Hint

Look at execution_table rows 1 and 5 for 'Parameter Value in Function'

If you remove the default value '= None' from 'q', what happens when the URL has no 'q' parameter?

A q becomes empty string

B q becomes None automatically

C FastAPI returns an error for missing required parameter

D Function returns null

💡 Hint

Default values make parameters optional; without default, parameter is required (see key_moments explanation)

Concept Snapshot

Basic query parameter declaration in FastAPI:
- Define function argument with type and optional default
- FastAPI reads query param from URL
- If missing, uses default value
- Returns parameter value in response
Example: async def read_items(q: str = None):

Full Transcript

This example shows how FastAPI handles basic query parameters. When a GET request is made to the endpoint, FastAPI looks for query parameters in the URL. It matches them to the function's arguments by name. If a query parameter is missing, FastAPI uses the default value specified in the function argument, here None. The function then returns the value it received. For example, if the URL is /items/?q=apple, the function receives 'apple' as q. If the URL has no q parameter, q is None. If q is empty like /items/?q=, q is an empty string. This behavior helps create flexible APIs that handle optional query parameters easily.

Practice

1. In FastAPI, how do you declare a query parameter that is optional with a default value?

easy

A. By importing Query from fastapi and not setting a default value

B. By using a special decorator like @query_param

C. By defining the parameter inside the request body

D. By adding a function parameter with a default value, e.g., def read_item(q: str = None)

Solution

1. Step 1: Understand query parameter declaration

   In FastAPI, query parameters are declared as function parameters in path operation functions.

2. Step 2: Recognize optional parameters

   If a parameter has a default value (like None), it becomes optional and is treated as a query parameter.

3. Final Answer:

   By adding a function parameter with a default value, e.g., def read_item(q: str = None) -> Option D

4. Quick Check:

   Optional query param = default value [OK]

Hint: Optional query params have default values in function signature [OK]

Common Mistakes:

• Thinking a decorator is needed for query params
• Confusing query params with request body
• Not setting a default value makes param required

2. Which of the following is the correct syntax to declare a required query parameter named item_id of type int in FastAPI?

easy

A. def read_item(item_id: int):

B. def read_item(item_id):

C. def read_item(item_id: str = 'default'):

D. def read_item(item_id: int = None):

Solution

1. Step 1: Identify required query parameter syntax

   A required query parameter has no default value and must have a type annotation.

2. Step 2: Check each option

   def read_item(item_id: int): declares item_id as an int without a default, making it required.

3. Final Answer:

   def read_item(item_id: int): -> Option A

4. Quick Check:

   Required param = no default value [OK]

Hint: No default means required query param [OK]

Common Mistakes:

• Setting default None makes param optional
• Using wrong type annotation
• Omitting type annotation makes param a path param

3. What will be the output if you call the FastAPI endpoint defined as below without any query parameters?

from fastapi import FastAPI
app = FastAPI()

@app.get('/items/')
def read_items(q: str = 'default'):
    return {'q': q}

medium

A. {'q': None}

B. Error: missing required query parameter

C. {'q': 'default'}

D. {'q': ''}

Solution

1. Step 1: Analyze the function parameter

   The parameter q has a default value of 'default', so it is optional.

2. Step 2: Understand the call without query params

   When no query parameter is provided, FastAPI uses the default value 'default'.

3. Final Answer:

   {'q': 'default'} -> Option C

4. Quick Check:

   Default value used when query param missing [OK]

Hint: Default param value is returned if query missing [OK]

Common Mistakes:

• Expecting None instead of default
• Thinking missing param causes error
• Assuming empty string is default

4. Identify the error in this FastAPI query parameter declaration:

from fastapi import FastAPI
app = FastAPI()

@app.get('/users/')
def get_user(user_id: int = None):
    return {'user_id': user_id}

medium

A. Default value None is invalid for int type without Optional

B. No error, this is a valid optional query parameter

C. Type hint should be Optional[int] from typing

D. Query parameter must be declared with Query()

Solution

1. Step 1: Check parameter declaration

   Declaring user_id: int = None makes it optional with default None.

2. Step 2: Verify FastAPI behavior

   FastAPI accepts this and treats user_id as an optional query parameter.

3. Final Answer:

   No error, this is a valid optional query parameter -> Option B

4. Quick Check:

   Default None with int type is allowed [OK]

Hint: Default None with int type is valid in FastAPI [OK]

Common Mistakes:

• Assuming Optional[int] is required
• Thinking Query() is mandatory
• Confusing type hints with runtime errors

5. You want to declare two query parameters in FastAPI: q which is optional with default None, and limit which is required and an integer. Which is the correct function signature?

hard

A. def read_items(limit: int, q: str = None):

B. def read_items(q: str = None, limit: int):

C. def read_items(q: str, limit: int = None):

D. def read_items(q: str = None, limit: int = 10):

Solution

1. Step 1: Understand parameter order rules

   In Python, parameters without defaults must come before those with defaults.

2. Step 2: Apply to FastAPI query params

   limit is required (no default), so it must come before optional q with default None.

3. Final Answer:

   def read_items(limit: int, q: str = None): -> Option A

4. Quick Check:

   Required params before optional ones [OK]

Hint: Put required params before optional ones in function signature [OK]

Common Mistakes:

• Placing optional param before required causes syntax error
• Assigning default to required param
• Mixing parameter order incorrectly