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.

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'}]