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

Concept Flow - Required query parameters

Client sends HTTP GET request

↓

FastAPI receives request

↓

Check for required query parameters

↓

Process request

↓

Send response back

FastAPI checks if required query parameters are present in the request. If missing, it returns an error; otherwise, it processes the request.

Execution Sample

FastAPI

from fastapi import FastAPI
app = FastAPI()

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

Defines a GET endpoint that requires a query parameter 'q'. If 'q' is missing, FastAPI returns an error automatically.

Execution Table

Step	Request URL	Query Parameter 'q'	Action	Response
1	/items/?q=book	'book'	Parameter present, process request	{"q": "book"}
2	/items/	missing	Parameter missing, return error	422 Unprocessable Entity

💡 Execution stops when FastAPI returns response or error based on presence of required query parameter 'q'.

Variable Tracker

Variable	Start	After Request 1	After Request 2
q	undefined	"book"	missing (error)

Key Moments - 2 Insights

Why does FastAPI return an error if the query parameter 'q' is missing?

Because 'q' is declared as a required parameter in the function signature, FastAPI automatically checks for it and returns a 422 error if it's not provided, as shown in execution_table row 2.

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

FastAPI passes the value of 'q' to the function and returns it in the response, as shown in execution_table row 1.

Visual Quiz - 3 Questions

Look at the execution table, what is the response when the URL is '/items/?q=book'?

A {"q": "book"}

B 422 Unprocessable Entity

C {}

D 404 Not Found

💡 Hint

Check execution_table row 1 under the Response column.

At which step does FastAPI return a 422 error?

A No error returned

B Step 1

C Step 2

D Both steps

💡 Hint

Look at execution_table row 2 under the Response column.

If you add a default value to 'q' like q: str = "default", how would the execution change?

A FastAPI would still return 422 if 'q' is missing

B FastAPI would use 'default' when 'q' is missing and not return an error

C FastAPI would ignore 'q' completely

D FastAPI would return 404 error

💡 Hint

Refer to variable_tracker and how default values affect required parameters.

Concept Snapshot

Required query parameters in FastAPI:
- Declare parameters in function without default value to make them required.
- FastAPI checks request for these parameters.
- Missing required parameters cause 422 error response.
- Present parameters are passed to function automatically.
- Use default values to make parameters optional.

Full Transcript

This example shows how FastAPI handles required query parameters. When a client sends a GET request to '/items/' with a query parameter 'q', FastAPI checks if 'q' is present. If it is, FastAPI passes the value to the function and returns it in the response. If 'q' is missing, FastAPI automatically returns a 422 Unprocessable Entity error. This behavior is because 'q' is declared as a required parameter without a default value. Adding a default value would make the parameter optional. The execution table traces these steps clearly, showing the request URL, parameter presence, action taken, and response returned. The variable tracker shows how the variable 'q' changes from undefined to a value or missing. Understanding this flow helps beginners see how FastAPI validates required query parameters and responds accordingly.

Practice

1. In FastAPI, how do you make a query parameter required so the client must provide it in the URL?

easy

A. Use Optional type hint

B. Set the parameter default to None

C. Use Query(...) in the function parameter

D. Use Body(...) instead of query

Solution

1. Step 1: Understand FastAPI query parameters

   FastAPI uses function parameters to define query parameters automatically.

2. Step 2: Use Query(...) to require parameter

   Using Query(...) tells FastAPI this parameter is required and must be in the URL.

3. Final Answer:

   Use Query(...) in the function parameter -> Option C

4. Quick Check:

   Required query parameter = Query(...) [OK]

Hint: Use Query(...) to make query parameters required [OK]

Common Mistakes:

• Setting default to None makes parameter optional
• Using Optional type hint allows missing parameter
• Using Body(...) defines body, not query parameter

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 = Query(None)):

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

C. def read_item(item_id: int = Body(...)):

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

Solution

1. Step 1: Identify required query parameter syntax

   To make a query parameter required, use Query(...) as the default value.

2. Step 2: Check each option

   def read_item(item_id: int = Query(...)): uses Query(...) correctly, making item_id required. def read_item(item_id: int = Query(None)): uses Query(None) which makes it optional. def read_item(item_id: int = None): uses default None without Query, optional. def read_item(item_id: int = Body(...)): uses Body(...) which makes it a required body field, not query parameter.

3. Final Answer:

   def read_item(item_id: int = Query(...)): -> Option D

4. Quick Check:

   Required query param = Query(...) [OK]

Hint: Use Query(...) as default to require query parameter [OK]

Common Mistakes:

• Using Query(None) makes parameter optional
• Using Body(...) for query parameter
• Setting default None makes parameter optional

3. Given this FastAPI endpoint code:

from fastapi import FastAPI, Query
app = FastAPI()

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

What happens if a client calls /items/ without the q query parameter?

medium

A. Returns HTTP 422 error for missing required query parameter

B. Returns HTTP 404 not found error

C. Returns empty JSON {}

D. Returns JSON with {"query": null}

Solution

1. Step 1: Understand Query(...) behavior

   Using Query(...) makes the parameter required. If missing, FastAPI returns an error automatically.

2. Step 2: Check what error FastAPI returns

   FastAPI returns HTTP 422 Unprocessable Entity error when a required query parameter is missing.

3. Final Answer:

   Returns HTTP 422 error for missing required query parameter -> Option A

4. Quick Check:

   Missing required query param = HTTP 422 error [OK]

Hint: Missing required query param causes HTTP 422 error [OK]

Common Mistakes:

• Expecting null or empty JSON instead of error
• Confusing 404 not found with parameter error
• Assuming optional parameter behavior

4. Identify the error in this FastAPI code snippet that tries to require a query parameter name:

from fastapi import FastAPI, Query
app = FastAPI()

@app.get("/users/")
async def get_user(name: str = Query(None)):
    return {"user": name}

medium

A. Missing type hint for name

B. The parameter is optional, not required

C. Query(...) should be replaced with Query(None)

D. Function should not be async

Solution

1. Step 1: Analyze Query parameter default

   The code uses Query(None) which means the parameter is optional.

2. Step 2: Check requirement for required parameter

   To make it required, it should use Query(...) instead of Query(None).

3. Final Answer:

   The parameter is optional, not required -> Option B

4. Quick Check:

   Query(None) = optional parameter [OK]

Hint: Query(None) means optional; use Query(...) for required [OK]

Common Mistakes:

• Confusing Query(None) with required parameter
• Ignoring type hints
• Thinking async keyword affects parameter requirement

5. You want to create a FastAPI endpoint that requires two query parameters: category (string) and limit (integer). Both must be required. Which code snippet correctly enforces this?

hard

A. async def get_items(category: str = Query(...), limit: int = Query(...)):

B. async def get_items(category: str = None, limit: int = None):

C. async def get_items(category: str, limit: int = Query(None)):

D. async def get_items(category: str = Query(None), limit: int = Query(...)):

Solution

1. Step 1: Understand required query parameters

   Both parameters must use Query(...) to be required.

2. Step 2: Evaluate each option

   async def get_items(category: str = Query(...), limit: int = Query(...)): correctly uses Query(...) for both. async def get_items(category: str = None, limit: int = None) uses None defaults, making them optional. async def get_items(category: str, limit: int = Query(None)) makes only limit optional. async def get_items(category: str = Query(None), limit: int = Query(...)) makes category optional.

3. Final Answer:

   async def get_items(category: str = Query(...), limit: int = Query(...)): -> Option A

4. Quick Check:

   Both required = Query(...) for each [OK]

Hint: Use Query(...) for each required query parameter [OK]

Common Mistakes:

• Setting default None makes parameter optional
• Mixing required and optional unintentionally
• Omitting Query makes parameter a path parameter