Query Parameters Basics 🔍

Query parameters are optional values passed in the URL after the `?` character. They're used for filtering, sorting, and pagination.

What are Query Parameters?

Query parameters appear after `?` in a URL:

/items?skip=0&limit=10
/users?search=john&sort=name
/products?category=electronics&price_min=100

Creating Query Parameters

@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10):
    # skip and limit have default values
    # /items → skip=0, limit=10
    # /items?skip=5 → skip=5, limit=10
    # /items?skip=5&limit=20 → skip=5, limit=20
    return {"skip": skip, "limit": limit}

Optional Parameters

from typing import Optional

@app.get("/search")
async def search(q: Optional[str] = None):
    # q is optional (can be None)
    if q:
        return {"results": ["item1", "item2"]}
    return {"message": "No search query"}

Multiple Parameters

@app.get("/products")
async def list_products(
    skip: int = 0,
    limit: int = 10,
    search: Optional[str] = None,
    category: Optional[str] = None
):
    # All are optional with defaults
    return {
        "skip": skip,
        "limit": limit,
        "search": search,
        "category": category
    }

Common Patterns

Pagination:

@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10):
    items = db.list_items(skip=skip, limit=limit)
    return {"items": items}

Filtering:

@app.get("/users")
async def list_users(status: str = "active"):
    users = db.list_users(status=status)
    return {"users": users}

Sorting:

@app.get("/products")
async def list_products(sort: str = "name", order: str = "asc"):
    return {"sort": sort, "order": order}

🔑 Key Takeaways

• ✅ Query parameters are optional by default

• ✅ Use defaults with `= value`

• ✅ Multiple parameters separated by `&`

• ✅ Common for pagination, filtering, sorting

• ✅ Use Optional for None values