Basic query parameter declaration in FastAPI - Deep Dive

Overview - Basic query parameter declaration

What is it?

Basic query parameter declaration in FastAPI means defining inputs that users can send in the URL after a question mark. These inputs help the server understand what data the user wants or how to filter results. FastAPI makes it easy to declare these parameters in your function so they are automatically read from the URL. This lets you build flexible web APIs that respond to different user requests.

Why it matters

Without query parameters, your web API would only accept fixed paths or body data, making it hard to customize responses. Query parameters let users specify details like search terms, filters, or pagination directly in the URL. This makes your API more powerful and user-friendly. Without this, users would need complicated requests or multiple endpoints for small variations.

Where it fits

Before learning query parameters, you should understand basic FastAPI route creation and Python function parameters. After this, you can learn about request bodies, path parameters, and validation to build more complex APIs.

Mental Model

Core Idea

Query parameters are named inputs in the URL that FastAPI automatically reads and passes as function arguments to customize API responses.

Think of it like...

It's like ordering coffee at a cafe where you specify your preferences (size, milk, sugar) by telling the barista. The barista listens and makes your coffee exactly how you want it.

URL example:
https://api.example.com/items?color=red&size=large

FastAPI function:
┌─────────────────────────────┐
│ def get_items(color: str, size: str): │
└─────────────────────────────┘

Flow:
User URL → FastAPI reads 'color' and 'size' → passes to function → function uses values

Build-Up - 7 Steps

1

Foundation

What are query parameters

Concept: Introduce the idea of query parameters as URL inputs after a question mark.

A query parameter is a key-value pair added to a URL after a question mark (?). For example, in https://example.com/items?color=blue, 'color' is the key and 'blue' is the value. These parameters let users send extra information to the server.

Result

You understand that query parameters are part of the URL and carry extra data.

Knowing query parameters exist helps you see how URLs can carry more than just the path, enabling dynamic requests.

2

Foundation

Declaring query parameters in FastAPI

Concept: Show how to declare query parameters as function arguments in FastAPI routes.

In FastAPI, you declare query parameters by adding function parameters with type hints. For example: from fastapi import FastAPI app = FastAPI() @app.get('/items') def read_items(color: str): return {'color': color} Here, 'color' is a query parameter automatically read from the URL.

Result

FastAPI reads the 'color' parameter from the URL and passes it to the function.

Understanding that function parameters become query parameters lets you quickly add inputs without extra code.

3

Intermediate

Optional query parameters with defaults

🤔Before reading on: Do you think query parameters must always be provided, or can they be optional with defaults? Commit to your answer.

Concept: Learn how to make query parameters optional by giving them default values.

You can make query parameters optional by assigning a default value in the function. For example: @app.get('/items') def read_items(color: str = 'red'): return {'color': color} If the user does not provide 'color', FastAPI uses 'red' automatically.

Result

The API works even if the query parameter is missing, using the default value.

Knowing how to set defaults prevents errors and makes your API more flexible for users.

4

Intermediate

Using multiple query parameters

🤔Before reading on: Can you declare more than one query parameter in a FastAPI function? Commit to yes or no.

Concept: Show how to declare multiple query parameters in one route function.

You can add many query parameters by listing them as function arguments: @app.get('/items') def read_items(color: str = 'red', size: int = 10): return {'color': color, 'size': size} Users can provide one, both, or none of these parameters.

Result

The API reads multiple parameters and uses defaults if some are missing.

Understanding multiple parameters lets you build richer APIs that accept many options.

5

Intermediate

Type validation of query parameters

🤔Before reading on: Do you think FastAPI automatically checks if query parameters match their declared types? Commit to yes or no.

Concept: Explain how FastAPI uses Python type hints to validate query parameter types automatically.

FastAPI reads the type hints like 'int' or 'str' and checks if the user input matches. For example: @app.get('/items') def read_items(size: int): return {'size': size} If the user sends size=abc, FastAPI returns an error because 'abc' is not an integer.

Result

FastAPI rejects invalid types and returns clear error messages.

Knowing automatic validation saves you from writing manual checks and improves API reliability.

6

Advanced

Using Query for extra metadata

🤔Before reading on: Do you think you can add descriptions or limits to query parameters in FastAPI? Commit to yes or no.

Concept: Introduce the Query class to add metadata like descriptions, default values, and validation rules.

FastAPI provides a Query helper to add extra info: from fastapi import Query @app.get('/items') def read_items(color: str = Query('red', min_length=3, max_length=10, description='Color name')): return {'color': color} This adds validation and helps generate API docs.

Result

Your API validates parameters more strictly and documents them automatically.

Using Query improves API quality and user experience by adding rules and clear docs.

7

Expert

Query parameters with complex types

🤔Before reading on: Can query parameters accept lists or multiple values in FastAPI? Commit to yes or no.

Concept: Explain how to declare query parameters that accept multiple values using lists.

You can declare a query parameter as a list to accept multiple values: from typing import List from fastapi import Query @app.get('/items') def read_items(colors: List[str] = Query([])): return {'colors': colors} Users can send ?colors=red&colors=blue to pass multiple colors.

Result

The API receives a list of values for one query parameter.

Knowing how to handle multiple values expands your API's flexibility for complex queries.

Under the Hood

FastAPI uses Python's type hints and function signatures to inspect route functions. When a request arrives, it parses the URL's query string, matches keys to function parameters, converts values to the declared types, and passes them to the function. If conversion fails, FastAPI returns an error response automatically. The Query class adds metadata that FastAPI uses for validation and documentation generation.

Why designed this way?

FastAPI was designed to leverage Python's modern features like type hints to reduce boilerplate and improve developer experience. Using function parameters for query parameters makes the code clean and intuitive. The automatic validation and docs generation reduce errors and speed up API development compared to manual parsing.

┌─────────────┐
│ HTTP Request│
│ URL: /items?color=red&size=10 │
└──────┬──────┘
       │
       ▼
┌─────────────────────────────┐
│ FastAPI Router inspects func │
│ Reads parameters: color:str, size:int │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ Parses query string          │
│ Converts 'red' to str, '10' to int │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ Calls function with args    │
│ read_items(color='red', size=10) │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think query parameters must always be strings? Commit to yes or no.

Common Belief: Query parameters are always strings and you must convert them manually.

Reality: FastAPI automatically converts query parameters to the declared Python types using type hints.

Why it matters: Believing this leads to unnecessary manual parsing and bugs, wasting time and complicating code.

Quick: Do you think missing query parameters cause server errors by default? Commit to yes or no.

Common Belief: If a query parameter is missing, the server will crash or return an error automatically.

Reality: If a query parameter has a default value, FastAPI uses it when the parameter is missing, preventing errors.

Why it matters: This misconception causes developers to write extra checks or avoid optional parameters, reducing API flexibility.

Quick: Do you think query parameters can only accept single values? Commit to yes or no.

Common Belief: Query parameters can only hold one value each, so multiple values require separate parameters.

Reality: FastAPI supports multiple values for the same query parameter by declaring it as a list type.

Why it matters: Not knowing this limits API design and forces awkward workarounds for multi-value inputs.

Quick: Do you think Query is only for setting default values? Commit to yes or no.

Common Belief: The Query helper is just a way to set default values for query parameters.

Reality: Query also adds validation rules, metadata, and helps generate API documentation automatically.

Why it matters: Ignoring Query's full power means missing out on cleaner validation and better API docs.

Expert Zone

1

FastAPI's dependency injection system can combine query parameters with other inputs like headers or cookies seamlessly.

2

Using Query with advanced validation (regex, min/max length) can prevent many common input errors early.

3

Query parameters are always strings in the URL, but FastAPI's conversion handles complex types transparently, including enums and nested models.

When NOT to use

Avoid using query parameters for large or sensitive data; use request bodies instead. Also, for required path-specific data, use path parameters rather than query parameters to keep URLs semantic.

Production Patterns

In production, query parameters are often combined with pagination, filtering, and sorting. FastAPI apps use Query with validation to ensure clients send correct data, and generate OpenAPI docs for easy frontend integration.

Connections

HTTP URL structure

Query parameters are part of the URL structure defined by HTTP standards.

Understanding URL anatomy helps grasp how query parameters fit into web requests and how servers parse them.

Function parameters in programming

FastAPI maps URL query parameters directly to Python function parameters.

Knowing how functions receive arguments clarifies how FastAPI connects web inputs to code logic.

Database query filtering

Query parameters often translate to database filters to retrieve specific data.

Recognizing this link helps design APIs that efficiently fetch only needed data, improving performance.

Common Pitfalls

#1 Forgetting to provide a default for optional query parameters causes errors.

Wrong approach:

from fastapi import FastAPI
app = FastAPI()

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

# Calling /items without ?color= fails

Correct approach:

from fastapi import FastAPI
app = FastAPI()

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

# Calling /items works with default 'blue'

Root cause:

Misunderstanding that parameters without defaults are required and must be provided.

#2 Declaring query parameters without type hints leads to them being ignored or treated as path parameters.

Wrong approach:

from fastapi import FastAPI
app = FastAPI()

@app.get('/items')
def read_items(color): # no type hint
return {'color': color}

Correct approach:

from fastapi import FastAPI
app = FastAPI()

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

Root cause:

Not using type hints prevents FastAPI from recognizing query parameters properly.

#3 Trying to send complex objects directly as query parameters instead of using request bodies.

Wrong approach:

from fastapi import FastAPI
app = FastAPI()

@app.get('/items')
def read_items(data: dict):
return data

# This will not work as expected

Correct approach:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
name: str
price: float

@app.post('/items')
def create_item(item: Item):
return item

Root cause:

Misusing query parameters for complex data that should be sent in the request body.

Key Takeaways

Query parameters are named inputs in the URL that FastAPI reads automatically as function arguments.

You can make query parameters optional by providing default values, improving API flexibility.

FastAPI uses Python type hints to validate and convert query parameters, reducing manual checks.

The Query helper adds validation rules and documentation metadata to query parameters.

Advanced usage includes accepting multiple values as lists and combining query parameters with other input types.

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