3. Path Parameters vs Query Parameters

URL Design Principles

In FastAPI, URLs are designed to represent resources rather than actions. Path parameters identify what resource is being accessed, while query parameters refine how that resource is requested. Clear URL design improves readability, consistency, and long-term API usability.

---

Strong Typing for Path Parameters

Path parameters in FastAPI are strictly typed and validated before request handling begins. This ensures that resource identifiers conform to expected formats and prevents invalid requests from reaching business logic. Strong typing at the path level enforces correctness at the most visible part of the API.

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return {"user_id": user_id}

---

Optional vs Required Query Parameters

Query parameters in FastAPI can be defined as required or optional using type hints and default values. Required queries enforce mandatory client input, while optional queries enable flexible filtering and pagination. This distinction allows APIs to remain expressive without becoming ambiguous.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
def list_items(category: str | None = None, limit: int = 10):
    return {"category": category, "limit": limit}

---

Validation Failures and Error Messages

FastAPI automatically validates both path and query parameters against declared types and constraints. When validation fails, the framework returns structured error responses with precise details about the failure. These standardized errors improve debuggability and enable clients to handle failures programmatically.