Path Parameters and Query Parameters

The Logic of Path Parameters

Path parameters are essential when you need to identify a specific resource within your application. When you define a route with curly braces, like '/users/{user_id}', you are instructing the framework to treat that part of the URL as a variable. FastAPI uses the type hints provided in your function signature to automatically parse and validate the input. If a user provides an alphabetical string where an integer is expected, the framework rejects the request immediately with a clear error, preventing invalid data from ever reaching your business logic. This declarative approach enforces a strict contract between the client and your code. By leveraging standard Python types, you ensure that the parameter inside your function behaves exactly as expected, whether it is an integer, a float, or a custom UUID, allowing for safe, predictable operations on your resources.

from fastapi import FastAPI

app = FastAPI()

# The variable 'item_id' is captured from the URL path.
# The type hint 'int' ensures FastAPI validates the input as a number.
@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}  # FastAPI converts the string path to an int

Understanding Query Parameters

Query parameters function differently from path parameters because they are not part of the URL path itself, but are appended to the URL after a question mark. They are ideal for optional data, filtering, sorting, or pagination logic. Because these parameters are defined as function arguments that are not part of the path, FastAPI automatically interprets any argument that does not match a path variable as a query parameter. This design allows for highly flexible endpoints where a client can choose to provide zero, some, or all available filters. If you provide a default value, the parameter becomes optional; if you omit the default, the parameter becomes mandatory. This mechanism provides a clean way to manage API complexity, ensuring that clients can request only the data they need without changing the fundamental structure of the endpoint path.

from fastapi import FastAPI

app = FastAPI()

# 'skip' and 'limit' are query parameters.
# They appear as ?skip=0&limit=10 in the request URL.
@app.get("/items/")
def read_items(skip: int = 0, limit: int = 10):
    # Return a simulated list based on query parameters
    return {"data": f"Items from {skip} to {skip + limit}"}

Required versus Optional Parameters

A critical aspect of API design is distinguishing between what is necessary to perform a task and what is merely helpful. In FastAPI, the distinction between required and optional parameters is handled through the presence of default values. When you define a path parameter, it is inherently required because the URL structure would be broken without it. However, query parameters are much more flexible. By setting a default value in the function signature, you explicitly declare that a parameter is optional. If the client does not provide it, the framework injects the default value into your function. This pattern allows you to write robust code that gracefully handles missing client data without needing verbose conditional checks. By strategically choosing your defaults, you create an API that is both easy to use for beginners and powerful for advanced power users.

from fastapi import FastAPI

app = FastAPI()

# 'q' is an optional query parameter with a default value of None.
@app.get("/search/")
def search_items(q: str = None):
    if q:
        return {"search_query": q}
    return {"message": "No search term provided"}

Data Validation and Conversion

FastAPI does more than just capture input; it performs heavy lifting regarding data validation and type conversion. When a request arrives, the framework inspects the incoming data and attempts to match it against your specified type hints. If the incoming value cannot be converted, such as passing text into an integer field, FastAPI generates a high-quality, JSON-formatted error message automatically. This is a massive time-saver, as it removes the need to write repetitive validation logic manually for every single endpoint. Because the conversion happens before your function code executes, you can work with your data as standard Python objects. This seamless integration ensures that you can focus on your business requirements rather than spending cycles on input parsing, error handling, and manual validation routines that are prone to bugs.

from fastapi import FastAPI

app = FastAPI()

# FastAPI ensures 'price' is a float and 'in_stock' is a boolean.
# If the user sends a string like 'abc', they get an automated 422 error.
@app.get("/products/{product_id}")
def get_product(product_id: int, price: float, in_stock: bool = True):
    return {"id": product_id, "price": price, "available": in_stock}

Combining Path and Query Parameters

You will frequently encounter scenarios where an API endpoint needs both specific resource identification and configuration options. Combining path and query parameters is straightforward: simply declare your path variables within the route string and define your query parameters as additional arguments in the function signature. FastAPI is intelligent enough to parse the path segments for the identifiers and look at the request URL for the query strings. This separation of concerns keeps your code readable and your URL structure intuitive. A well-designed endpoint often uses the path to define 'what' resource is being accessed and query parameters to define 'how' the response should be formatted. By organizing your API this way, you create a self-documenting interface that feels natural to users and remains easy to maintain as your project requirements grow in complexity.

from fastapi import FastAPI

app = FastAPI()

# Path parameter: user_id
# Query parameter: active_only
@app.get("/users/{user_id}/orders")
def get_user_orders(user_id: int, active_only: bool = False):
    return {"user": user_id, "only_active": active_only}

Interview questions

All FastAPI interview questions →

Check yourself

Take the full FastAPI quiz →