FastAPI Path Parameters and Query Parameters

Parameter handling is the boundary between untrusted client input and your core business logic. In traditional frameworks, validation is an afterthought — you manually cast strings, check for None, and pray edge cases don't slip through. I've seen that pattern collapse under production load more times than I'd like to admit.

FastAPI inverts this model entirely. By leveraging Python's type hinting system, parameters become a typed contract. FastAPI validates against a schema, converts to the correct Python object, and generates interactive OpenAPI documentation — all from your function signature alone. There is no separate validation layer to synchronize, no schema file to keep in sync with your code.

The distinction between path and query parameters is not cosmetic. Path parameters identify a specific resource — they are hierarchical, always required, and semantically load-bearing. Query parameters modify the representation of that resource — they are non-hierarchical, often optional, and composable. Mixing them up produces confusing APIs that frustrate clients, break caching strategies, and signal a shaky understanding of REST resource modeling to anyone reading your routes.

How FastAPI Path and Query Parameters Actually Work

FastAPI path parameters and query parameters are the two mechanisms for extracting dynamic values from a request URL. Path parameters are declared as named placeholders in the route string (e.g., /items/{item_id}) and are required by default. Query parameters are key-value pairs appended after the '?' in the URL (e.g., ?skip=0&limit=10) and are optional unless given a default of ... (Ellipsis). FastAPI uses Python type hints to automatically parse, validate, and convert these parameters into the declared types, returning a 422 validation error if the input doesn't match.

Path parameters are positional and tightly coupled to the endpoint's resource hierarchy — they identify a specific entity (like a user ID or product slug). Query parameters are for filtering, sorting, pagination, or optional modifiers. FastAPI treats all function parameters that are not declared in the path as query parameters by default. This means a simple typo — forgetting to include a parameter in the path — silently turns it into a query parameter, which can break client contracts.

Use path parameters for mandatory resource identifiers that form part of the URL structure. Use query parameters for optional or semi-optional modifiers that don't change the resource identity. This distinction matters because search engines, API gateways, and caching layers treat path and query parameters differently — paths are often cached as-is, while query strings may be ignored or normalized.

Path Parameters: Resource Identification

Path parameters exist for one reason: to uniquely identify a resource within your URL hierarchy. They are not filters, they are not options, and they are not toggles. If you find yourself putting something optional into a path segment, that is a design smell worth stopping to examine.

FastAPI supports a special syntax called 'Path Converters' that extend the default matching behavior. The most important is the :path converter — it tells FastAPI to match everything remaining in the URL, including forward slashes. Without it, a path parameter stops at the first / it encounters. This makes :path essential for building file explorers, storage proxies, or any service where the resource identifier is itself a hierarchical path.

Path parameters are inherently required at the routing level. If a client omits a path segment, the route simply does not match — the response is a 404, not a 422. The 422 only appears after route matching succeeds and FastAPI attempts to validate the captured value against your type hint and any Path() constraints. This two-stage process means your validation logic never has to handle a missing path parameter; the router handles that before Pydantic is involved.

from fastapi import FastAPI, Path
from typing import Annotated

app = FastAPI()


@app.get('/forge/users/{user_id}')
def get_user_by_id(
    # Annotated keeps the base type visible to IDEs and type checkers.
    # Path() attaches validation metadata without polluting the default value.
    user_id: Annotated[
        int,
        Path(
            title='User ID',
            description='The internal registry ID of the user. Must be a positive integer.',
            ge=1,
        ),
    ],
):
    """
    Fetch a single user from the internal forge registry by their numeric ID.
    IDs start at 1 — zero and negatives are rejected at the boundary.
    """
    return {'user_id': user_id, 'context': 'internal_forge_registry'}


# The :path converter is required for any parameter that may contain slashes.
# Without it, /forge/assets/images/branding/logo.png would bind only
# 'images' to file_path and the route would 404 on the remainder.
@app.get('/forge/assets/{file_path:path}')
def get_asset_stream(file_path: str):
    """
    Stream a static asset by its full storage path, including subdirectories.
    file_path captures everything after /forge/assets/ including slashes.
    """
    return {'requested_path': file_path}


# GET /forge/users/42
# -> {'user_id': 42, 'context': 'internal_forge_registry'}

# GET /forge/users/0
# -> 422 Unprocessable Entity (ge=1 constraint violated)

# GET /forge/assets/images/branding/logo.png
# -> {'requested_path': 'images/branding/logo.png'}

Query Parameters: Filtering and Pagination

Query parameters handle everything that modifies how a resource is represented, rather than which resource you are talking about. Filtering a list by status, sorting results by a field, paginating through a large dataset — these all belong in query parameters. They appear after the ? in the URL, are separated by &, and carry no positional significance. /search?q=fastapi&page=2 is semantically identical to /search?page=2&q=fastapi — order does not matter.

In FastAPI, any function argument that does not appear in the route path string is automatically treated as a query parameter. Providing a default value makes it optional. Omitting the default makes it required — FastAPI will reject requests without it and return a 422 with a clear error pointing at the missing field.

FastAPI also supports multi-value query parameters natively. Define a parameter as list[str] and the client sends the same key multiple times: ?tag=python&tag=web&tag=api. FastAPI collects all values and delivers them as a Python list. There is no custom parsing logic required on your end. If the client sends no values for a list parameter, the result is an empty list — unless you set a default with Query().

One thing worth being deliberate about: the boolean type in FastAPI is more permissive than you might expect. It accepts 'true', '1', 'on', 'yes', 'True' as True and their inverses as False. This is intentional — it makes the API compatible with curl, shell scripts, and frontend libraries that serialize booleans differently. Know this behavior exists so it does not surprise you in testing.

from fastapi import FastAPI
from typing import Optional

app = FastAPI()


@app.get('/forge/search')
def list_artifacts(
    query: str,                    # Required — no default means the client must provide this
    page: int = 1,                 # Optional — defaults to page 1 if not provided
    tag: Optional[str] = None,     # Optional — defaults to None, filtering is skipped
    active: bool = True,           # FastAPI accepts 'true', '1', 'yes' as True
):
    """
    Search artifacts in the forge registry.

    - query: full-text search term (required)
    - page: pagination offset, 1-indexed (optional, default 1)
    - tag: filter results to a specific tag (optional)
    - active: include only active artifacts when True (optional, default True)
    """
    return {
        'search_term': query,
        'pagination': {'page': page},
        'filter': {'tag': tag, 'active': active},
    }


# GET /forge/search?query=api
# -> {'search_term': 'api', 'pagination': {'page': 1}, 'filter': {'tag': None, 'active': True}}

# GET /forge/search?query=api&page=3&tag=infra&active=false
# -> {'search_term': 'api', 'pagination': {'page': 3}, 'filter': {'tag': 'infra', 'active': False}}

# GET /forge/search
# -> 422 Unprocessable Entity (query is required, no default provided)

Complex Validation with Query()

Type hints handle the common case — an integer is an integer, a string is a string. But real production APIs have business rules that go beyond type correctness. A service identifier must start with a specific prefix. A pagination limit must be between 1 and 100. A search term must be at least three characters long. These are not type constraints; they are domain constraints, and they belong at the API boundary, not buried inside your business logic.

The Query() class is how you express those constraints in FastAPI. It accepts ge (greater than or equal), gt (greater than), le (less than or equal), lt (less than), min_length, max_length, and pattern for regular expression matching. Every constraint is enforced by Pydantic before your function body executes — a request that violates any constraint is rejected with a structured 422 response containing the field name, the failed constraint, and a human-readable message.

The Annotated pattern is the right way to combine Query() with your type hint. Annotated[str, Query(min_length=3, pattern='^FORGE-.*$')] keeps the base type (str) visible to IDEs and type checkers, while attaching the validation metadata separately. The older pattern — param: str = Query(min_length=3) — works but conflates the default value position with the Query object, which confuses IDEs and breaks autocompletion in some editors.

One constraint worth measuring before you ship: regex patterns via Query(pattern=...) run on every request. A poorly anchored or backtracking-prone regex on a high-traffic endpoint will show up in your profiler. Always anchor your patterns (use ^ and $), test them against pathological inputs, and benchmark them under load before deploying on hot paths. For simple guards like minimum length or maximum value, prefer the numeric and length constraints over regex — they are faster and the error messages are clearer.

from fastapi import FastAPI, Query
from typing import Annotated

app = FastAPI()


@app.get('/forge/audit-logs')
def get_audit_logs(
    # service_id must start with 'FORGE-' and be at least 3 characters.
    # Annotated keeps str visible to IDEs; Query() attaches the constraints.
    service_id: Annotated[
        str,
        Query(
            title='Service Identifier',
            description='Internal service ID. Must use the FORGE- prefix.',
            min_length=3,
            pattern='^FORGE-.*$',
        ),
    ],
    # limit is optional (defaults to 20) but must be between 1 and 100.
    # Query() on a default value enforces the constraint on every request,
    # including those that omit the parameter and trigger the default.
    limit: Annotated[
        int,
        Query(
            title='Result Limit',
            description='Maximum number of log entries to return. Range: 1–100.',
            ge=1,
            le=100,
        ),
    ] = 20,
):
    """
    Retrieve audit log entries for a specific internal service.

    Both parameters are validated before this function body runs.
    Invalid input never reaches the log query logic.
    """
    return {'service': service_id, 'limit': limit}


# GET /forge/audit-logs?service_id=FORGE-AUTH&limit=50
# -> {'service': 'FORGE-AUTH', 'limit': 50}

# GET /forge/audit-logs?service_id=EXTERNAL-SVC&limit=50
# -> 422 Unprocessable Entity
# -> detail: [{'loc': ['query', 'service_id'], 'msg': 'String should match pattern ...', 'type': 'string_pattern_mismatch'}]

# GET /forge/audit-logs?service_id=FORGE-AUTH&limit=500
# -> 422 Unprocessable Entity
# -> detail: [{'loc': ['query', 'limit'], 'msg': 'Input should be less than or equal to 100', 'type': 'less_than_equal'}]

Why Type Enforcement on Path Parameters Prevents Production Outages

Last Tuesday, a junior pushed a change that accepted 'item_id' as a string. The endpoint parsed fine in development. But when a client sent a malformed ID like 'ABC-123', the database driver choked on the implicit type cast. The endpoint returned a 500, and we spent an hour tracing the routing logic. The fix? FastAPI's type enforcement at the path parameter level. When you declare a path parameter as an integer, FastAPI automatically validates the input before your handler runs. It returns a 422 validation failure to the client — not a 500 internal error. This shifts the failure boundary to the edge of your API, where it belongs. You never want to trust data extracted from a URL. URLs are user-generated text. Type hints on path parameters are your first line of defense. They force the framework to reject garbage early. 'item_id: int' tells FastAPI: reject anything that isn't a valid integer. No manual parsing. No defensive code. Just a declarative contract that the client must honor.

# io.thecodeforge
from fastapi import FastAPI, HTTPException

app = FastAPI()

db = {1: "Widget A", 2: "Widget B"}

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    """
    item_id is validated as integer BEFORE this function runs.
    If client sends /items/foo, FastAPI returns 422.
    """
    item = db.get(item_id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item_id": item_id, "name": item}

Query Parameters: The Silent Bottleneck in Pagination

I've debugged three production incidents where a missing query parameter caused a database to return millions of rows. The culprit: optional query parameters with no defaults. Consider a search endpoint. The client forgot to include 'limit'. Without a default, your handler tries to execute a SELECT * FROM products — no limit clause. The database chokes, memory spikes, and your API times out. The fix is defensive defaults. Use Query(...) with a 'default' of 'None' and then apply a fallback. But better: set a hard cap. 'limit: int = Query(10, ge=1, le=100)' enforces a minimum of 1 and a maximum of 100. This protects the database and the client. Clients who send 'limit=10000' get a 422 error. They learn to respect boundaries. You also avoid the 'infinite limit' bug. FastAPI's Query() function gives you that guardrail for free. If you have a 'skip' parameter, make sure it's non-negative: 'skip: int = Query(0, ge=0)'. A negative 'skip' is meaningless and could cause an SQL injection vector if concatenated unsafely. Always clamp query parameters that control resource consumption.

# io.thecodeforge
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/products/")
async def list_products(
    category: str | None = None,
    skip: int = Query(0, ge=0),
    limit: int = Query(10, ge=1, le=100)
):
    """
    Default limit=10 prevents accidental full table scans.
    ge=1 ensures at least one row requested.
    le=100 caps the max pagination size.
    """
    products = [
        {"id": i, "name": f"Product {i}", "cat": category or "all"}
        for i in range(skip, skip + limit)
    ]
    return {"items": products, "count": len(products)}