Basic query parameter declaration in FastAPI

Introduction

Query parameters let users send extra information in the URL to customize what the server returns.

When you want to filter results, like searching for books by author name.

When you want to sort data, like showing newest items first.

When you want to paginate results, like showing page 2 of a list.

When you want to pass optional settings without changing the URL path.

Syntax

FastAPI

from fastapi import FastAPI

app = FastAPI()

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

Query parameters are declared as function parameters with default values.

If you give a default value, the parameter is optional.

Examples

Here, q is a required query parameter. The user must provide it in the URL.

FastAPI

from fastapi import FastAPI

app = FastAPI()

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

Here, q is optional. If the user does not provide it, q will be None.

FastAPI

from fastapi import FastAPI

app = FastAPI()

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

Here, q has a default value of "default" if not provided by the user.

FastAPI

from fastapi import FastAPI

app = FastAPI()

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

Sample Program

This program creates a simple API endpoint /items/ that accepts an optional query parameter q. If the user provides q, it returns a message showing what was searched. Otherwise, it says no query was provided.

FastAPI

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
async def read_items(q: str = None):
    if q:
        return {"message": f"You searched for: {q}"}
    else:
        return {"message": "No search query provided."}

Important Notes

Query parameters appear after a question mark in the URL, like /items/?q=book.

FastAPI automatically converts query parameters to the declared type, like int or str.

Use None as a default to make parameters optional.

Summary

Query parameters let users send extra info in the URL to customize responses.

Declare them as function parameters with default values in FastAPI.

Parameters with defaults are optional; without defaults are required.

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