How do path and query parameters work?

Question

Accepted Answer

FastAPI extracts **path parameters** (part of the URL path) and **query parameters** (after `?`) from function arguments, using type hints to convert and validate them automatically.

## Path parameters — part of the URL

```python
@app.get("/items/{item_id}")        # {item_id} in the path
def get_item(item_id: int):          # matched by NAME; `int` converts & validates
    return {"item_id": item_id}
# GET /items/5 → item_id = 5 (int).  GET /items/abc → 422 error (not an int)
```

A function parameter whose name matches a `{placeholder}` in the path becomes a **path parameter**. The type hint (`int`) auto-converts the string from the URL and returns a clear 422 error if it doesn't match.

## Query parameters — everything else

```python
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, q: str | None = None):
    # parameters NOT in the path become QUERY parameters
    # GET /items?skip=20&limit=5&q=phone → skip=20, limit=5, q="phone"
    return {"skip": skip, "limit": limit, "q": q}
```

Function parameters **not** in the path become **query parameters**. A default value makes them optional (`skip: int = 0`); `str | None = None` makes a nullable optional query param. Without a default, they're required.

## Required vs optional

```python
def search(q: str):              # REQUIRED query param (no default) → ?q=... must be present
def search(q: str = ""):          # optional, defaults to ""
def search(q: str | None = None): # optional, defaults to None
```

## Combining both

```python
@app.get("/users/{user_id}/items")
def user_items(user_id: int, limit: int = 10):
    # user_id = path param, limit = query param — distinguished by the path
```

## Why it matters

Path and query parameters are how endpoints receive input from the URL — fundamental to nearly every API route (fetching a resource by id, filtering, paginating, searching).

FastAPI's approach is elegant and a key reason it's productive: simply declaring typed function parameters gives you automatic extraction, **type conversion**, **validation** (with clear 422 errors on bad input), and required-vs-optional semantics (via defaults) — all derived from standard Python type hints, with no manual parsing.

Understanding the distinction (path params come from `{placeholders}`, everything else is a query param) and how defaults control optionality is essential everyday knowledge for building FastAPI endpoints.