Query Parameters
Part of: FastAPI Basics
Learn to handle query parameters in URLs. Create flexible endpoints that accept optional parameters for filtering, pagination, and customization.
What You'll Learn
- Understand what query parameters are and how they work
- Create endpoints that accept optional query parameters
- Set default values for query parameters
- Use type hints for automatic query parameter validation
- Handle both path and query parameters together
Theory and Concepts
Query Parameters
🎯 What You'll Learn
Query parameters are a powerful way to make your APIs flexible by accepting optional parameters in the URL. Following the official FastAPI tutorial, you'll learn how to handle URL parameters that come after the ? symbol.
By the end of this lesson, you'll understand how to:
- Understand what query parameters are and how they work
- Create endpoints that accept optional query parameters
- Set default values for query parameters
- Use type hints for automatic query parameter validation
- Handle both path and query parameters together
🔍 What are Query Parameters?
Query parameters are the optional parts of a URL that come after the ? symbol. They're used to modify or filter the response without changing the core endpoint.
Real-World Examples
You see query parameters everywhere:
- Google Search: google.com/search?q=fastapi&lang=en
- YouTube: youtube.com/results?search_query=python
- Online stores: store.com/products?category=electronics&sort=price
- Pagination: api.com/users?page=2&limit=20
🔧 How Query Parameters Work
Basic Syntax
When you declare other function parameters that are not part of the path parameters, they are automatically interpreted as "query" parameters.
[Code Example]
How it works:
- /items/ → Uses defaults: skip=0, limit=10
- /items/?skip=20 → Uses: skip=20, limit=10 (default)
- /items/?skip=20&limit=10 → Uses: skip=20, limit=10
🎨 Query Parameter Features
Default Values
Query parameters can have default values, making them optional:
[Code Example]
Optional Parameters
You can make parameters truly optional by setting them to None:
[Code Example]
URL Examples:
- /items/foo → {"item_id": "foo"}
- /items/foo?q=search → {"item_id": "foo", "q": "search"}
Type Conversion
FastAPI automatically converts query parameters to the specified types:
[Code Example]
URL Examples:
- /items/?skip=5&limit=20&active=false
- /items/?active=1 (1 becomes True)
- /items/?active=0 (0 becomes False)
💡 Official Tutorial Examples
Example 1: Simple Query Parameters
From the official tutorial:
[Code Example]
Test it:
- /items/ → Returns first 10 items
- /items/?skip=1 → Skips first item, returns next 10
- /items/?limit=2 → Returns first 2 items
Example 2: Combining Path and Query Parameters
[Code Example]
Test it:
- /items/foo → {"item_id": "foo"}
- /items/foo?q=search → {"item_id": "foo", "q": "search"}
Example 3: Multiple Query Parameters
[Code Example]
🌟 Advanced Query Parameter Features
Required Query Parameters
Make query parameters required by not providing a default value:
[Code Example]
Multiple Types
[Code Example]
List Parameters
[Code Example]
URL: /items/?tags=python&tags=fastapi&tags=tutorial
✨ Best Practices
1. Use Meaningful Default Values
[Code Example]
2. Use Type Hints
[Code Example]
3. Handle Optional Parameters Properly
[Code Example]
🚫 Common Beginner Mistakes
Mistake 1: Forgetting Default Values
[Code Example]
Mistake 2: Wrong Optional Syntax
[Code Example]
Mistake 3: Not Handling None Values
[Code Example]
🎉 What's Next?
Congratulations! You now understand how to use query parameters to make your APIs flexible and user-friendly. This is essential for building real-world APIs that need filtering, pagination, and customization.
You've learned:
- How query parameters work in URLs
- Setting default values for optional parameters
- Combining path and query parameters
- Handling None values for optional parameters
Coming up next: Request Body - learning how to handle POST requests with data in the request body!
📖 Additional Resources
- FastAPI Query Parameters Guide
- HTTP Query Parameters Explained
- REST API Query Parameter Best Practices
Helpful Hint
Query parameters come after the ? in URLs like /items/?skip=0&limit=10. Define them as function parameters with default values!